aliaslive-sdk 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# alias-sdk
+
+Official JavaScript / TypeScript SDK for [alias.live](https://aliasurlshortener.com).
+
+## Install
+
+```bash
+npm install aliaslive-sdk
+```
+
+## Quick start
+
+```ts
+import { AliasClient } from 'aliaslive-sdk';
+
+const alias = new AliasClient({ apiKey: 'alias_xxxxxxxxxxxx' });
+
+// Shorten a single URL
+const { shortUrl } = await alias.shorten('https://example.com/very-long-path');
+console.log(shortUrl); // https://alias.live/abc123
+
+// Custom slug
+const result = await alias.shorten('https://example.com', { slug: 'my-link' });
+
+// With password and expiry
+const result = await alias.shorten('https://example.com', {
+  slug:      'secret',
+  password:  'hunter2',
+  expiresAt: '2025-12-31T23:59:59Z',
+});
+```
+
+## Bulk shortening
+
+```ts
+const results = await alias.bulkShorten([
+  { destination: 'https://example.com/page-one' },
+  { destination: 'https://example.com/page-two', slug: 'page-two' },
+]);
+
+for (const r of results) {
+  if (r.error) {
+    console.error(`Failed: ${r.destination} — ${r.error}`);
+  } else {
+    console.log(`${r.destination} → ${r.shortUrl}`);
+  }
+}
+```
+
+## Link management
+
+```ts
+// List links (paginated)
+const { links, total } = await alias.links.list();
+const page2 = await alias.links.list(2, 20);
+
+// Delete
+await alias.links.delete('my-link');
+
+// Analytics
+const stats = await alias.links.analytics('my-link', { days: 30 });
+console.log(stats.total_clicks);
+console.log(stats.countries);
+```
+
+## Error handling
+
+```ts
+import { AliasClient, AliasHttpError } from 'alias-sdk';
+
+try {
+  await alias.shorten('https://example.com', { slug: 'taken' });
+} catch (err) {
+  if (err instanceof AliasHttpError) {
+    console.error(err.status, err.code, err.message);
+    // 409 CONFLICT Slug already exists
+  }
+}
+```
+
+## API key
+
+Generate one at [aliasurlshortener.com/account](https://aliasurlshortener.com/account) → API Keys.
+
+## CommonJS
+
+```js
+const { AliasClient } = require('aliaslive-sdk');
+```

package/dist/index.cjs

@@ -0,0 +1,142 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AliasClient: () => AliasClient,
+  AliasHttpError: () => HttpError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var HttpError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "AliasHttpError";
+  }
+};
+async function request(baseUrl, apiKey, method, path, body, params) {
+  const url = new URL(`${baseUrl}${path}`);
+  if (params) {
+    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));
+  }
+  const res = await fetch(url.toString(), {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "X-Api-Key": apiKey
+    },
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const json = await res.json();
+  if (!res.ok || !json.success) {
+    throw new HttpError(res.status, json.error?.code ?? "UNKNOWN", json.error?.message ?? `HTTP ${res.status}`);
+  }
+  return json.data;
+}
+var LinksNamespace = class {
+  constructor(_req) {
+    this._req = _req;
+  }
+  /** List links. Paginated — default 10 per page. */
+  async list(page = 1, limit = 10) {
+    const raw = await this._req("GET", "/links", void 0, { page, limit });
+    return {
+      links: raw.result,
+      total: raw.total,
+      totalClicks: raw.total_clicks,
+      page: raw.page,
+      limit: raw.limit
+    };
+  }
+  /** Delete a link by slug. */
+  delete(slug) {
+    return this._req("DELETE", `/links/${encodeURIComponent(slug)}`);
+  }
+  /** Get click analytics for a link. */
+  analytics(slug, options) {
+    return this._req("GET", `/links/${encodeURIComponent(slug)}/analytics`, void 0, {
+      days: options?.days ?? 30
+    });
+  }
+};
+var AliasClient = class {
+  constructor({ apiKey, baseUrl = "https://alias.live/api/v1" }) {
+    if (!apiKey) throw new Error("AliasClient: apiKey is required");
+    this._base = baseUrl.replace(/\/$/, "");
+    this._key = apiKey;
+    this.links = new LinksNamespace(this._req.bind(this));
+  }
+  _req(method, path, body, params) {
+    return request(this._base, this._key, method, path, body, params);
+  }
+  /**
+   * Shorten a single URL.
+   *
+   * @example
+   * const { shortUrl } = await alias.shorten('https://example.com');
+   * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+   */
+  async shorten(destination, options = {}) {
+    const { slug, password, expiresAt } = options;
+    const data = await this._req("POST", "/customShort", {
+      destination,
+      ...slug ? { slug } : {},
+      ...password ? { password } : {},
+      ...expiresAt ? { expires_at: expiresAt } : {}
+    });
+    return {
+      slug: data.slug,
+      shortUrl: `https://alias.live/${data.slug}`,
+      destination
+    };
+  }
+  /**
+   * Shorten multiple URLs in one request (max 50).
+   *
+   * @example
+   * const results = await alias.bulkShorten([
+   *   { destination: 'https://a.com' },
+   *   { destination: 'https://b.com', slug: 'b-link' },
+   * ]);
+   */
+  async bulkShorten(items) {
+    if (items.length === 0) return [];
+    if (items.length > 50) throw new Error("bulkShorten: max 50 items per call");
+    const data = await this._req(
+      "POST",
+      "/links/bulk",
+      { links: items }
+    );
+    return data.results.map((r) => ({
+      destination: r.destination,
+      slug: r.slug,
+      shortUrl: r.short_url,
+      error: r.error
+    }));
+  }
+};
+var index_default = AliasClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AliasClient,
+  AliasHttpError
+});

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+/**
+ * Alias URL Shortener — Official JavaScript / TypeScript SDK
+ *
+ * @example
+ * ```ts
+ * import { AliasClient } from 'aliaslive-sdk';
+ *
+ * const alias = new AliasClient({ apiKey: 'alias_xxxx' });
+ *
+ * const { shortUrl } = await alias.shorten('https://example.com');
+ * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+ * const results      = await alias.bulkShorten([{ destination: 'https://a.com' }]);
+ * const { links }    = await alias.links.list();
+ * await alias.links.delete('my-link');
+ * const analytics    = await alias.links.analytics('my-link');
+ * ```
+ */
+interface AliasClientOptions {
+    /** API key from aliasurlshortener.com/account */
+    apiKey: string;
+    /** Override the API base URL (default: https://alias.live/api/v1) */
+    baseUrl?: string;
+}
+interface ShortenOptions {
+    /** Custom slug (letters, numbers, _ or - ; max 40 chars) */
+    slug?: string;
+    /** Password to protect the link */
+    password?: string;
+    /** Expiry as an ISO-8601 datetime string */
+    expiresAt?: string;
+}
+interface ShortenResult {
+    slug: string;
+    shortUrl: string;
+    destination: string;
+}
+interface BulkItem {
+    destination: string;
+    slug?: string;
+}
+interface BulkResult {
+    destination: string;
+    slug?: string;
+    shortUrl?: string;
+    error?: string;
+}
+interface Link {
+    slug: string;
+    destination: string;
+    view_count: number;
+    created_at: string;
+    expires_at?: string | null;
+    has_password: boolean;
+    created_via: string;
+}
+interface LinksPage {
+    links: Link[];
+    total: number;
+    totalClicks: number;
+    page: number;
+    limit: number;
+}
+interface Analytics {
+    total_clicks: number;
+    daily: {
+        date: string;
+        clicks: number;
+    }[];
+    countries: {
+        country: string;
+        count: number;
+    }[];
+    devices: {
+        device: string;
+        count: number;
+    }[];
+    browsers: {
+        browser: string;
+        count: number;
+    }[];
+    referrers: {
+        referrer: string;
+        count: number;
+    }[];
+}
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class LinksNamespace {
+    private readonly _req;
+    constructor(_req: <T>(m: string, p: string, b?: unknown, q?: Record<string, string | number>) => Promise<T>);
+    /** List links. Paginated — default 10 per page. */
+    list(page?: number, limit?: number): Promise<LinksPage>;
+    /** Delete a link by slug. */
+    delete(slug: string): Promise<void>;
+    /** Get click analytics for a link. */
+    analytics(slug: string, options?: {
+        days?: number;
+    }): Promise<Analytics>;
+}
+declare class AliasClient {
+    private readonly _base;
+    private readonly _key;
+    /** Namespaced link operations: list, delete, analytics. */
+    readonly links: LinksNamespace;
+    constructor({ apiKey, baseUrl }: AliasClientOptions);
+    private _req;
+    /**
+     * Shorten a single URL.
+     *
+     * @example
+     * const { shortUrl } = await alias.shorten('https://example.com');
+     * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+     */
+    shorten(destination: string, options?: ShortenOptions): Promise<ShortenResult>;
+    /**
+     * Shorten multiple URLs in one request (max 50).
+     *
+     * @example
+     * const results = await alias.bulkShorten([
+     *   { destination: 'https://a.com' },
+     *   { destination: 'https://b.com', slug: 'b-link' },
+     * ]);
+     */
+    bulkShorten(items: BulkItem[]): Promise<BulkResult[]>;
+}
+
+export { AliasClient, type AliasClientOptions, HttpError as AliasHttpError, type Analytics, type BulkItem, type BulkResult, type Link, type LinksPage, type ShortenOptions, type ShortenResult, AliasClient as default };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Alias URL Shortener — Official JavaScript / TypeScript SDK
+ *
+ * @example
+ * ```ts
+ * import { AliasClient } from 'aliaslive-sdk';
+ *
+ * const alias = new AliasClient({ apiKey: 'alias_xxxx' });
+ *
+ * const { shortUrl } = await alias.shorten('https://example.com');
+ * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+ * const results      = await alias.bulkShorten([{ destination: 'https://a.com' }]);
+ * const { links }    = await alias.links.list();
+ * await alias.links.delete('my-link');
+ * const analytics    = await alias.links.analytics('my-link');
+ * ```
+ */
+interface AliasClientOptions {
+    /** API key from aliasurlshortener.com/account */
+    apiKey: string;
+    /** Override the API base URL (default: https://alias.live/api/v1) */
+    baseUrl?: string;
+}
+interface ShortenOptions {
+    /** Custom slug (letters, numbers, _ or - ; max 40 chars) */
+    slug?: string;
+    /** Password to protect the link */
+    password?: string;
+    /** Expiry as an ISO-8601 datetime string */
+    expiresAt?: string;
+}
+interface ShortenResult {
+    slug: string;
+    shortUrl: string;
+    destination: string;
+}
+interface BulkItem {
+    destination: string;
+    slug?: string;
+}
+interface BulkResult {
+    destination: string;
+    slug?: string;
+    shortUrl?: string;
+    error?: string;
+}
+interface Link {
+    slug: string;
+    destination: string;
+    view_count: number;
+    created_at: string;
+    expires_at?: string | null;
+    has_password: boolean;
+    created_via: string;
+}
+interface LinksPage {
+    links: Link[];
+    total: number;
+    totalClicks: number;
+    page: number;
+    limit: number;
+}
+interface Analytics {
+    total_clicks: number;
+    daily: {
+        date: string;
+        clicks: number;
+    }[];
+    countries: {
+        country: string;
+        count: number;
+    }[];
+    devices: {
+        device: string;
+        count: number;
+    }[];
+    browsers: {
+        browser: string;
+        count: number;
+    }[];
+    referrers: {
+        referrer: string;
+        count: number;
+    }[];
+}
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare class LinksNamespace {
+    private readonly _req;
+    constructor(_req: <T>(m: string, p: string, b?: unknown, q?: Record<string, string | number>) => Promise<T>);
+    /** List links. Paginated — default 10 per page. */
+    list(page?: number, limit?: number): Promise<LinksPage>;
+    /** Delete a link by slug. */
+    delete(slug: string): Promise<void>;
+    /** Get click analytics for a link. */
+    analytics(slug: string, options?: {
+        days?: number;
+    }): Promise<Analytics>;
+}
+declare class AliasClient {
+    private readonly _base;
+    private readonly _key;
+    /** Namespaced link operations: list, delete, analytics. */
+    readonly links: LinksNamespace;
+    constructor({ apiKey, baseUrl }: AliasClientOptions);
+    private _req;
+    /**
+     * Shorten a single URL.
+     *
+     * @example
+     * const { shortUrl } = await alias.shorten('https://example.com');
+     * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+     */
+    shorten(destination: string, options?: ShortenOptions): Promise<ShortenResult>;
+    /**
+     * Shorten multiple URLs in one request (max 50).
+     *
+     * @example
+     * const results = await alias.bulkShorten([
+     *   { destination: 'https://a.com' },
+     *   { destination: 'https://b.com', slug: 'b-link' },
+     * ]);
+     */
+    bulkShorten(items: BulkItem[]): Promise<BulkResult[]>;
+}
+
+export { AliasClient, type AliasClientOptions, HttpError as AliasHttpError, type Analytics, type BulkItem, type BulkResult, type Link, type LinksPage, type ShortenOptions, type ShortenResult, AliasClient as default };

package/dist/index.js

@@ -0,0 +1,116 @@
+// src/index.ts
+var HttpError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "AliasHttpError";
+  }
+};
+async function request(baseUrl, apiKey, method, path, body, params) {
+  const url = new URL(`${baseUrl}${path}`);
+  if (params) {
+    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));
+  }
+  const res = await fetch(url.toString(), {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      "X-Api-Key": apiKey
+    },
+    body: body !== void 0 ? JSON.stringify(body) : void 0
+  });
+  const json = await res.json();
+  if (!res.ok || !json.success) {
+    throw new HttpError(res.status, json.error?.code ?? "UNKNOWN", json.error?.message ?? `HTTP ${res.status}`);
+  }
+  return json.data;
+}
+var LinksNamespace = class {
+  constructor(_req) {
+    this._req = _req;
+  }
+  /** List links. Paginated — default 10 per page. */
+  async list(page = 1, limit = 10) {
+    const raw = await this._req("GET", "/links", void 0, { page, limit });
+    return {
+      links: raw.result,
+      total: raw.total,
+      totalClicks: raw.total_clicks,
+      page: raw.page,
+      limit: raw.limit
+    };
+  }
+  /** Delete a link by slug. */
+  delete(slug) {
+    return this._req("DELETE", `/links/${encodeURIComponent(slug)}`);
+  }
+  /** Get click analytics for a link. */
+  analytics(slug, options) {
+    return this._req("GET", `/links/${encodeURIComponent(slug)}/analytics`, void 0, {
+      days: options?.days ?? 30
+    });
+  }
+};
+var AliasClient = class {
+  constructor({ apiKey, baseUrl = "https://alias.live/api/v1" }) {
+    if (!apiKey) throw new Error("AliasClient: apiKey is required");
+    this._base = baseUrl.replace(/\/$/, "");
+    this._key = apiKey;
+    this.links = new LinksNamespace(this._req.bind(this));
+  }
+  _req(method, path, body, params) {
+    return request(this._base, this._key, method, path, body, params);
+  }
+  /**
+   * Shorten a single URL.
+   *
+   * @example
+   * const { shortUrl } = await alias.shorten('https://example.com');
+   * const { shortUrl } = await alias.shorten('https://example.com', { slug: 'my-link' });
+   */
+  async shorten(destination, options = {}) {
+    const { slug, password, expiresAt } = options;
+    const data = await this._req("POST", "/customShort", {
+      destination,
+      ...slug ? { slug } : {},
+      ...password ? { password } : {},
+      ...expiresAt ? { expires_at: expiresAt } : {}
+    });
+    return {
+      slug: data.slug,
+      shortUrl: `https://alias.live/${data.slug}`,
+      destination
+    };
+  }
+  /**
+   * Shorten multiple URLs in one request (max 50).
+   *
+   * @example
+   * const results = await alias.bulkShorten([
+   *   { destination: 'https://a.com' },
+   *   { destination: 'https://b.com', slug: 'b-link' },
+   * ]);
+   */
+  async bulkShorten(items) {
+    if (items.length === 0) return [];
+    if (items.length > 50) throw new Error("bulkShorten: max 50 items per call");
+    const data = await this._req(
+      "POST",
+      "/links/bulk",
+      { links: items }
+    );
+    return data.results.map((r) => ({
+      destination: r.destination,
+      slug: r.slug,
+      shortUrl: r.short_url,
+      error: r.error
+    }));
+  }
+};
+var index_default = AliasClient;
+export {
+  AliasClient,
+  HttpError as AliasHttpError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "aliaslive-sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript / TypeScript SDK for alias.live URL shortener",
+  "keywords": ["url-shortener", "alias", "sdk", "short-links"],
+  "author": "Harsh Malkani",
+  "license": "MIT",
+  "homepage": "https://aliasurlshortener.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/harshmalkani/alias-sdk.git"
+  },
+  "type": "module",
+  "main":    "./dist/index.cjs",
+  "module":  "./dist/index.js",
+  "types":   "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types":   "./dist/index.d.ts",
+      "import":  "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev":   "tsup src/index.ts --format esm,cjs --dts --watch"
+  },
+  "devDependencies": {
+    "tsup":       "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": { "node": ">=18" }
+}