@clipr/core 0.0.5

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+/** A shortened URL entry stored in the URL database. */
+interface UrlEntry {
+    /** The short slug (e.g. "abc123"). */
+    slug: string;
+    /** The original long URL to redirect to. */
+    url: string;
+    /** ISO 8601 timestamp when the entry was created. */
+    createdAt: string;
+    /** Optional expiration as ISO 8601 timestamp. */
+    expiresAt?: string;
+    /** Optional human-readable description. */
+    description?: string;
+    /** UTM parameters to append on redirect. */
+    utm?: UtmParams;
+}
+/** UTM campaign tracking parameters. */
+interface UtmParams {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+/** The shape of the urls.json database file. */
+interface UrlDatabase {
+    /** Schema version for future migrations. */
+    version: number;
+    /** Auto-incrementing counter (unused if slugs are random/custom). */
+    counter: number;
+    /** Base URL for short links (e.g. "https://clpr.sh"). */
+    baseUrl: string;
+    /** Map of slug -> URL entry. */
+    urls: Record<string, UrlEntry>;
+}
+/** Result of a validation check. */
+type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/** Supported backend storage types. */
+type BackendType = 'json' | 'cloudflare-kv' | 'redis';
+/** Deployment mode for the CLI. */
+type DeployMode = 'github' | 'api';
+/** Configuration for a clipr project. */
+interface CliprConfig {
+    /** Deployment mode. */
+    mode: DeployMode;
+    /** Where to store URL data. */
+    backend: BackendType;
+    /** Base URL for short links. */
+    baseUrl: string;
+    /** Default slug length for random slugs. */
+    slugLength: number;
+    /** Path to the urls.json file (for json backend). */
+    dbPath: string;
+    /** GitHub backend config. */
+    github?: {
+        owner: string;
+        repo: string;
+        branch: string;
+        path: string;
+        token: string;
+    };
+    /** API backend config (Workers). */
+    api?: {
+        baseUrl: string;
+        token: string;
+    };
+}
+/** Options for creating a short URL. */
+interface CreateOptions {
+    /** Custom slug (auto-generated if omitted). */
+    slug?: string;
+    /** Tags for organization. */
+    tags?: string[];
+    /** Expiration date (ISO 8601). */
+    expiresAt?: string;
+    /** Password for protected links. */
+    password?: string;
+    /** Description. */
+    description?: string;
+    /** UTM parameters. */
+    utm?: UtmParams;
+    /** Custom OG title. */
+    ogTitle?: string;
+    /** Custom OG description. */
+    ogDescription?: string;
+    /** Custom OG image URL. */
+    ogImage?: string;
+}
+/** Options for listing URLs. */
+interface ListOptions {
+    /** Filter by tag. */
+    tag?: string;
+    /** Search query (slug, URL, description). */
+    search?: string;
+    /** Max results. */
+    limit?: number;
+    /** Output format. */
+    format?: 'table' | 'json';
+}
+/** A fully resolved short URL with all metadata. */
+interface ShortUrl extends UrlEntry {
+    /** Tags for organization. */
+    tags?: string[];
+    /** Whether the slug was custom or auto-generated. */
+    custom?: boolean;
+    /** Password hash (for protected links). */
+    passwordHash?: string;
+    /** Custom OG title. */
+    ogTitle?: string;
+    /** Custom OG description. */
+    ogDescription?: string;
+    /** Custom OG image URL. */
+    ogImage?: string;
+}
+/** Result of resolving a slug. */
+interface ResolveResult {
+    /** The target URL to redirect to (with UTM appended if applicable). */
+    url: string;
+    /** Whether the link is password-protected. */
+    passwordProtected: boolean;
+    /** Whether the link has expired. */
+    expired: boolean;
+}
+/** Click analytics for a link (Workers API mode only). */
+interface LinkStats {
+    /** Total clicks. */
+    total: number;
+    /** Clicks per day. */
+    daily: Record<string, number>;
+    /** Clicks by country. */
+    geo: Record<string, number>;
+    /** Clicks by device type. */
+    device: Record<string, number>;
+    /** Clicks by referrer domain. */
+    referrer: Record<string, number>;
+}
+/** The full urls.json manifest shape (alias for UrlDatabase). */
+type UrlsManifest = UrlDatabase;
+
+/**
+ * Simple backend interface for basic CRUD operations.
+ * Used by JsonBackend and KvBackend.
+ */
+interface Backend {
+    /** Get a URL entry by slug. Returns undefined if not found. */
+    get(slug: string): Promise<ShortUrl | undefined>;
+    /** Store a new URL entry. Throws SlugConflictError if slug exists. */
+    set(entry: ShortUrl): Promise<void>;
+    /** Delete a URL entry by slug. Returns true if it existed. */
+    delete(slug: string): Promise<boolean>;
+    /** Check if a slug exists. */
+    has(slug: string): Promise<boolean>;
+    /** List all URL entries. */
+    list(): Promise<ShortUrl[]>;
+}
+/**
+ * Full backend interface (Strategy pattern) as specified in the plan.
+ * Includes create/resolve/update/getStats for CLI and Worker use.
+ */
+interface UrlBackend {
+    /** Create a new short URL. */
+    create(slug: string, targetUrl: string, options?: CreateOptions): Promise<ShortUrl>;
+    /** Resolve a slug to its target URL. Returns null if not found. */
+    resolve(slug: string): Promise<ResolveResult | null>;
+    /** List short URLs with optional filtering. */
+    list(options?: ListOptions): Promise<ShortUrl[]>;
+    /** Delete a short URL by slug. */
+    delete(slug: string): Promise<void>;
+    /** Update an existing short URL. */
+    update(slug: string, updates: Partial<ShortUrl>): Promise<ShortUrl>;
+    /** Get click analytics for a slug. Returns null if backend doesn't support stats. */
+    getStats(slug: string): Promise<LinkStats | null>;
+}
+
+/** Resolve the path to ~/.clipr.json. */
+declare function resolveConfigPath(): string;
+/** Load config from ~/.clipr.json, falling back to defaults. */
+declare function loadConfig(path?: string): CliprConfig;
+/** Save config to ~/.clipr.json. */
+declare function saveConfig(config: CliprConfig, path?: string): void;
+/** Merge partial user config with defaults. */
+declare function resolveConfig(partial?: Partial<CliprConfig>): CliprConfig;
+/** Validate that a backend type is recognized. */
+declare function isValidBackend(value: string): value is BackendType;
+
+/** Default slug length when generating random slugs. */
+declare const DEFAULT_SLUG_LENGTH = 6;
+/** Minimum allowed slug length. */
+declare const MIN_SLUG_LENGTH = 3;
+/** Maximum allowed slug length. */
+declare const MAX_SLUG_LENGTH = 32;
+/** Characters used in random slug generation (URL-safe, no ambiguous chars). */
+declare const SLUG_ALPHABET = "abcdefghijkmnpqrstuvwxyz23456789";
+/** Maximum allowed URL length in characters. */
+declare const MAX_URL_LENGTH = 2048;
+/** Reserved slugs that cannot be used (common paths + locale codes). */
+declare const RESERVED_SLUGS: Set<string>;
+/** Default database file path relative to project root. */
+declare const DEFAULT_DB_PATH = "urls.json";
+/** Current URL database schema version. */
+declare const DB_VERSION = 1;
+
+/** Base error class for all clipr errors. */
+declare class CliprError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Thrown when a slug is invalid (bad chars, reserved, wrong length). */
+declare class InvalidSlugError extends CliprError {
+    constructor(slug: string, reason: string);
+}
+/** Thrown when a URL fails validation. */
+declare class InvalidUrlError extends CliprError {
+    constructor(url: string, reason: string);
+}
+/** Thrown when a slug already exists in the database. */
+declare class SlugConflictError extends CliprError {
+    constructor(slug: string);
+}
+/** Thrown when a slug is not found in the database. */
+declare class SlugNotFoundError extends CliprError {
+    constructor(slug: string);
+}
+/** Thrown when the backend configuration is invalid or missing. */
+declare class BackendError extends CliprError {
+    constructor(message: string);
+}
+
+declare class JsonBackend implements Backend {
+    private readonly path;
+    constructor(path: string);
+    private read;
+    private write;
+    get(slug: string): Promise<UrlEntry | undefined>;
+    set(entry: UrlEntry): Promise<void>;
+    delete(slug: string): Promise<boolean>;
+    has(slug: string): Promise<boolean>;
+    list(): Promise<UrlEntry[]>;
+    /** Update the baseUrl in the database. */
+    setBaseUrl(baseUrl: string): Promise<void>;
+    /** Get the current baseUrl. */
+    getBaseUrl(): Promise<string>;
+}
+
+/**
+ * Generate a slug from a counter value using Sqids.
+ * Deterministic: same counter always produces same slug.
+ */
+declare function generateSlug(counter: number): string;
+/**
+ * Decode a Sqids-generated slug back to its counter value.
+ * Returns the counter number, or null if invalid.
+ */
+declare function decodeSlug(slug: string): number | null;
+/**
+ * Generate a random slug using crypto.getRandomValues.
+ * Used when no counter is available.
+ */
+declare function generateRandomSlug(length?: number): string;
+/** Check if a string is a valid slug format. */
+declare function isValidSlug(slug: string): boolean;
+/** Normalize a slug to lowercase and trimmed. */
+declare function normalizeSlug(slug: string): string;
+
+/** Append UTM parameters to a URL string. Existing UTM params on the URL are overwritten. */
+declare function appendUtm(url: string, utm: UtmParams): string;
+/** Extract UTM parameters from a URL string. */
+declare function extractUtm(url: string): UtmParams;
+/** Check if a UtmParams object has any non-empty values. */
+declare function hasUtm(utm: UtmParams | undefined): utm is UtmParams;
+
+/** Validate a slug string. */
+declare function validateSlug(slug: string): ValidationResult;
+/** Validate a target URL. */
+declare function validateUrl(url: string): ValidationResult;
+
+export { type Backend, BackendError, type BackendType, type CliprConfig, CliprError, type CreateOptions, DB_VERSION, DEFAULT_DB_PATH, DEFAULT_SLUG_LENGTH, type DeployMode, InvalidSlugError, InvalidUrlError, JsonBackend, type LinkStats, type ListOptions, MAX_SLUG_LENGTH, MAX_URL_LENGTH, MIN_SLUG_LENGTH, RESERVED_SLUGS, type ResolveResult, SLUG_ALPHABET, type ShortUrl, SlugConflictError, SlugNotFoundError, type UrlBackend, type UrlDatabase, type UrlEntry, type UrlsManifest, type UtmParams, type ValidationResult, appendUtm, decodeSlug, extractUtm, generateRandomSlug, generateSlug, hasUtm, isValidBackend, isValidSlug, loadConfig, normalizeSlug, resolveConfig, resolveConfigPath, saveConfig, validateSlug, validateUrl };

package/dist/index.js

@@ -0,0 +1,313 @@
+// src/config.ts
+import { readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// src/constants.ts
+var DEFAULT_SLUG_LENGTH = 6;
+var MIN_SLUG_LENGTH = 3;
+var MAX_SLUG_LENGTH = 32;
+var SLUG_ALPHABET = "abcdefghijkmnpqrstuvwxyz23456789";
+var MAX_URL_LENGTH = 2048;
+var RESERVED_SLUGS = /* @__PURE__ */ new Set([
+  // Routes
+  "api",
+  "admin",
+  "dashboard",
+  "health",
+  "login",
+  "logout",
+  "signup",
+  "settings",
+  "password",
+  "shorten",
+  // Static files
+  "static",
+  "assets",
+  "favicon.ico",
+  "robots.txt",
+  "sitemap.xml",
+  "sitemap-index.xml",
+  // i18n locale codes (prevent conflicts with Astro SSG routes)
+  "en",
+  "es",
+  "fr",
+  "de",
+  "pt",
+  "ru",
+  "zh",
+  "hi",
+  "ar",
+  "ur",
+  "bn",
+  "ja"
+]);
+var DEFAULT_DB_PATH = "urls.json";
+var DB_VERSION = 1;
+
+// src/config.ts
+var DEFAULT_CONFIG = {
+  mode: "github",
+  backend: "json",
+  baseUrl: "",
+  slugLength: DEFAULT_SLUG_LENGTH,
+  dbPath: DEFAULT_DB_PATH
+};
+function resolveConfigPath() {
+  return join(homedir(), ".clipr.json");
+}
+function loadConfig(path) {
+  const configPath = path ?? resolveConfigPath();
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return resolveConfig(parsed);
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+function saveConfig(config, path) {
+  const configPath = path ?? resolveConfigPath();
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+`);
+}
+function resolveConfig(partial = {}) {
+  return { ...DEFAULT_CONFIG, ...partial };
+}
+function isValidBackend(value) {
+  return value === "json" || value === "cloudflare-kv" || value === "redis";
+}
+
+// src/errors.ts
+var CliprError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CliprError";
+  }
+};
+var InvalidSlugError = class extends CliprError {
+  constructor(slug, reason) {
+    super(`Invalid slug "${slug}": ${reason}`, "INVALID_SLUG");
+    this.name = "InvalidSlugError";
+  }
+};
+var InvalidUrlError = class extends CliprError {
+  constructor(url, reason) {
+    super(`Invalid URL "${url}": ${reason}`, "INVALID_URL");
+    this.name = "InvalidUrlError";
+  }
+};
+var SlugConflictError = class extends CliprError {
+  constructor(slug) {
+    super(`Slug "${slug}" already exists`, "SLUG_CONFLICT");
+    this.name = "SlugConflictError";
+  }
+};
+var SlugNotFoundError = class extends CliprError {
+  constructor(slug) {
+    super(`Slug "${slug}" not found`, "SLUG_NOT_FOUND");
+    this.name = "SlugNotFoundError";
+  }
+};
+var BackendError = class extends CliprError {
+  constructor(message) {
+    super(message, "BACKEND_ERROR");
+    this.name = "BackendError";
+  }
+};
+
+// src/json-backend.ts
+import { readFile, writeFile } from "fs/promises";
+function emptyDb() {
+  return { version: DB_VERSION, counter: 0, baseUrl: "", urls: {} };
+}
+var JsonBackend = class {
+  constructor(path) {
+    this.path = path;
+  }
+  async read() {
+    try {
+      const raw = await readFile(this.path, "utf-8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return emptyDb();
+      }
+      throw err;
+    }
+  }
+  async write(db) {
+    await writeFile(this.path, `${JSON.stringify(db, null, 2)}
+`);
+  }
+  async get(slug) {
+    const db = await this.read();
+    return db.urls[slug];
+  }
+  async set(entry) {
+    const db = await this.read();
+    if (db.urls[entry.slug]) {
+      throw new SlugConflictError(entry.slug);
+    }
+    db.urls[entry.slug] = entry;
+    db.counter = Object.keys(db.urls).length;
+    await this.write(db);
+  }
+  async delete(slug) {
+    const db = await this.read();
+    if (!db.urls[slug]) {
+      return false;
+    }
+    delete db.urls[slug];
+    db.counter = Object.keys(db.urls).length;
+    await this.write(db);
+    return true;
+  }
+  async has(slug) {
+    const db = await this.read();
+    return slug in db.urls;
+  }
+  async list() {
+    const db = await this.read();
+    return Object.values(db.urls);
+  }
+  /** Update the baseUrl in the database. */
+  async setBaseUrl(baseUrl) {
+    const db = await this.read();
+    db.baseUrl = baseUrl;
+    await this.write(db);
+  }
+  /** Get the current baseUrl. */
+  async getBaseUrl() {
+    const db = await this.read();
+    return db.baseUrl;
+  }
+};
+
+// src/slug.ts
+import Sqids from "sqids";
+var sqids = new Sqids({ alphabet: SLUG_ALPHABET, minLength: 4 });
+function generateSlug(counter) {
+  return sqids.encode([counter]);
+}
+function decodeSlug(slug) {
+  const decoded = sqids.decode(slug);
+  return decoded.length > 0 ? decoded[0] ?? null : null;
+}
+function generateRandomSlug(length = DEFAULT_SLUG_LENGTH) {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let slug = "";
+  for (let i = 0; i < length; i++) {
+    slug += SLUG_ALPHABET[bytes[i] % SLUG_ALPHABET.length];
+  }
+  return slug;
+}
+function isValidSlug(slug) {
+  if (slug.length < 1 || slug.length > 32) return false;
+  return /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(slug);
+}
+function normalizeSlug(slug) {
+  return slug.trim().toLowerCase();
+}
+
+// src/utm.ts
+var UTM_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"];
+function appendUtm(url, utm) {
+  const parsed = new URL(url);
+  for (const key of UTM_KEYS) {
+    const value = utm[key];
+    if (value !== void 0 && value !== "") {
+      parsed.searchParams.set(key, value);
+    }
+  }
+  return parsed.toString();
+}
+function extractUtm(url) {
+  const parsed = new URL(url);
+  const result = {};
+  for (const key of UTM_KEYS) {
+    const value = parsed.searchParams.get(key);
+    if (value !== null) {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function hasUtm(utm) {
+  if (!utm) return false;
+  return UTM_KEYS.some((key) => utm[key] !== void 0 && utm[key] !== "");
+}
+
+// src/validate.ts
+var SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+function validateSlug(slug) {
+  if (slug.length < MIN_SLUG_LENGTH) {
+    return { valid: false, reason: `must be at least ${MIN_SLUG_LENGTH} characters` };
+  }
+  if (slug.length > MAX_SLUG_LENGTH) {
+    return { valid: false, reason: `must be at most ${MAX_SLUG_LENGTH} characters` };
+  }
+  if (!SLUG_PATTERN.test(slug)) {
+    return {
+      valid: false,
+      reason: "must contain only lowercase letters, numbers, and hyphens (no leading/trailing hyphens)"
+    };
+  }
+  if (RESERVED_SLUGS.has(slug)) {
+    return { valid: false, reason: "is a reserved slug" };
+  }
+  return { valid: true };
+}
+function validateUrl(url) {
+  if (url.length === 0) {
+    return { valid: false, reason: "URL cannot be empty" };
+  }
+  if (url.length > MAX_URL_LENGTH) {
+    return { valid: false, reason: `URL exceeds maximum length of ${MAX_URL_LENGTH} characters` };
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { valid: false, reason: "not a valid URL" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { valid: false, reason: "only http and https URLs are allowed" };
+  }
+  return { valid: true };
+}
+export {
+  BackendError,
+  CliprError,
+  DB_VERSION,
+  DEFAULT_DB_PATH,
+  DEFAULT_SLUG_LENGTH,
+  InvalidSlugError,
+  InvalidUrlError,
+  JsonBackend,
+  MAX_SLUG_LENGTH,
+  MAX_URL_LENGTH,
+  MIN_SLUG_LENGTH,
+  RESERVED_SLUGS,
+  SLUG_ALPHABET,
+  SlugConflictError,
+  SlugNotFoundError,
+  appendUtm,
+  decodeSlug,
+  extractUtm,
+  generateRandomSlug,
+  generateSlug,
+  hasUtm,
+  isValidBackend,
+  isValidSlug,
+  loadConfig,
+  normalizeSlug,
+  resolveConfig,
+  resolveConfigPath,
+  saveConfig,
+  validateSlug,
+  validateUrl
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/constants.ts","../src/errors.ts","../src/json-backend.ts","../src/slug.ts","../src/utm.ts","../src/validate.ts"],"sourcesContent":["import { readFileSync, writeFileSync } from 'node:fs';\nimport { homedir } from 'node:os';\nimport { join } from 'node:path';\nimport { DEFAULT_DB_PATH, DEFAULT_SLUG_LENGTH } from './constants.js';\nimport type { BackendType, CliprConfig } from './types.js';\n\nconst DEFAULT_CONFIG: CliprConfig = {\n  mode: 'github',\n  backend: 'json',\n  baseUrl: '',\n  slugLength: DEFAULT_SLUG_LENGTH,\n  dbPath: DEFAULT_DB_PATH,\n};\n\n/** Resolve the path to ~/.clipr.json. */\nexport function resolveConfigPath(): string {\n  return join(homedir(), '.clipr.json');\n}\n\n/** Load config from ~/.clipr.json, falling back to defaults. */\nexport function loadConfig(path?: string): CliprConfig {\n  const configPath = path ?? resolveConfigPath();\n  try {\n    const raw = readFileSync(configPath, 'utf-8');\n    const parsed = JSON.parse(raw) as Partial<CliprConfig>;\n    return resolveConfig(parsed);\n  } catch {\n    return { ...DEFAULT_CONFIG };\n  }\n}\n\n/** Save config to ~/.clipr.json. */\nexport function saveConfig(config: CliprConfig, path?: string): void {\n  const configPath = path ?? resolveConfigPath();\n  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\\n`);\n}\n\n/** Merge partial user config with defaults. */\nexport function resolveConfig(partial: Partial<CliprConfig> = {}): CliprConfig {\n  return { ...DEFAULT_CONFIG, ...partial };\n}\n\n/** Validate that a backend type is recognized. */\nexport function isValidBackend(value: string): value is BackendType {\n  return value === 'json' || value === 'cloudflare-kv' || value === 'redis';\n}\n","/** Default slug length when generating random slugs. */\nexport const DEFAULT_SLUG_LENGTH = 6;\n\n/** Minimum allowed slug length. */\nexport const MIN_SLUG_LENGTH = 3;\n\n/** Maximum allowed slug length. */\nexport const MAX_SLUG_LENGTH = 32;\n\n/** Characters used in random slug generation (URL-safe, no ambiguous chars). */\nexport const SLUG_ALPHABET = 'abcdefghijkmnpqrstuvwxyz23456789';\n\n/** Maximum allowed URL length in characters. */\nexport const MAX_URL_LENGTH = 2048;\n\n/** Reserved slugs that cannot be used (common paths + locale codes). */\nexport const RESERVED_SLUGS = new Set([\n  // Routes\n  'api',\n  'admin',\n  'dashboard',\n  'health',\n  'login',\n  'logout',\n  'signup',\n  'settings',\n  'password',\n  'shorten',\n  // Static files\n  'static',\n  'assets',\n  'favicon.ico',\n  'robots.txt',\n  'sitemap.xml',\n  'sitemap-index.xml',\n  // i18n locale codes (prevent conflicts with Astro SSG routes)\n  'en',\n  'es',\n  'fr',\n  'de',\n  'pt',\n  'ru',\n  'zh',\n  'hi',\n  'ar',\n  'ur',\n  'bn',\n  'ja',\n]);\n\n/** Default database file path relative to project root. */\nexport const DEFAULT_DB_PATH = 'urls.json';\n\n/** Current URL database schema version. */\nexport const DB_VERSION = 1;\n","/** Base error class for all clipr errors. */\nexport class CliprError extends Error {\n  constructor(\n    message: string,\n    public readonly code: string,\n  ) {\n    super(message);\n    this.name = 'CliprError';\n  }\n}\n\n/** Thrown when a slug is invalid (bad chars, reserved, wrong length). */\nexport class InvalidSlugError extends CliprError {\n  constructor(slug: string, reason: string) {\n    super(`Invalid slug \"${slug}\": ${reason}`, 'INVALID_SLUG');\n    this.name = 'InvalidSlugError';\n  }\n}\n\n/** Thrown when a URL fails validation. */\nexport class InvalidUrlError extends CliprError {\n  constructor(url: string, reason: string) {\n    super(`Invalid URL \"${url}\": ${reason}`, 'INVALID_URL');\n    this.name = 'InvalidUrlError';\n  }\n}\n\n/** Thrown when a slug already exists in the database. */\nexport class SlugConflictError extends CliprError {\n  constructor(slug: string) {\n    super(`Slug \"${slug}\" already exists`, 'SLUG_CONFLICT');\n    this.name = 'SlugConflictError';\n  }\n}\n\n/** Thrown when a slug is not found in the database. */\nexport class SlugNotFoundError extends CliprError {\n  constructor(slug: string) {\n    super(`Slug \"${slug}\" not found`, 'SLUG_NOT_FOUND');\n    this.name = 'SlugNotFoundError';\n  }\n}\n\n/** Thrown when the backend configuration is invalid or missing. */\nexport class BackendError extends CliprError {\n  constructor(message: string) {\n    super(message, 'BACKEND_ERROR');\n    this.name = 'BackendError';\n  }\n}\n","import { readFile, writeFile } from 'node:fs/promises';\nimport type { Backend } from './backend.js';\nimport { DB_VERSION } from './constants.js';\nimport { SlugConflictError } from './errors.js';\nimport type { UrlDatabase, UrlEntry } from './types.js';\n\nfunction emptyDb(): UrlDatabase {\n  return { version: DB_VERSION, counter: 0, baseUrl: '', urls: {} };\n}\n\nexport class JsonBackend implements Backend {\n  constructor(private readonly path: string) {}\n\n  private async read(): Promise<UrlDatabase> {\n    try {\n      const raw = await readFile(this.path, 'utf-8');\n      return JSON.parse(raw) as UrlDatabase;\n    } catch (err: unknown) {\n      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n        return emptyDb();\n      }\n      throw err;\n    }\n  }\n\n  private async write(db: UrlDatabase): Promise<void> {\n    await writeFile(this.path, `${JSON.stringify(db, null, 2)}\\n`);\n  }\n\n  async get(slug: string): Promise<UrlEntry | undefined> {\n    const db = await this.read();\n    return db.urls[slug];\n  }\n\n  async set(entry: UrlEntry): Promise<void> {\n    const db = await this.read();\n    if (db.urls[entry.slug]) {\n      throw new SlugConflictError(entry.slug);\n    }\n    db.urls[entry.slug] = entry;\n    db.counter = Object.keys(db.urls).length;\n    await this.write(db);\n  }\n\n  async delete(slug: string): Promise<boolean> {\n    const db = await this.read();\n    if (!db.urls[slug]) {\n      return false;\n    }\n    delete db.urls[slug];\n    db.counter = Object.keys(db.urls).length;\n    await this.write(db);\n    return true;\n  }\n\n  async has(slug: string): Promise<boolean> {\n    const db = await this.read();\n    return slug in db.urls;\n  }\n\n  async list(): Promise<UrlEntry[]> {\n    const db = await this.read();\n    return Object.values(db.urls);\n  }\n\n  /** Update the baseUrl in the database. */\n  async setBaseUrl(baseUrl: string): Promise<void> {\n    const db = await this.read();\n    db.baseUrl = baseUrl;\n    await this.write(db);\n  }\n\n  /** Get the current baseUrl. */\n  async getBaseUrl(): Promise<string> {\n    const db = await this.read();\n    return db.baseUrl;\n  }\n}\n","import Sqids from 'sqids';\nimport { DEFAULT_SLUG_LENGTH, SLUG_ALPHABET } from './constants.js';\n\nconst sqids = new Sqids({ alphabet: SLUG_ALPHABET, minLength: 4 });\n\n/**\n * Generate a slug from a counter value using Sqids.\n * Deterministic: same counter always produces same slug.\n */\nexport function generateSlug(counter: number): string {\n  return sqids.encode([counter]);\n}\n\n/**\n * Decode a Sqids-generated slug back to its counter value.\n * Returns the counter number, or null if invalid.\n */\nexport function decodeSlug(slug: string): number | null {\n  const decoded = sqids.decode(slug);\n  return decoded.length > 0 ? (decoded[0] ?? null) : null;\n}\n\n/**\n * Generate a random slug using crypto.getRandomValues.\n * Used when no counter is available.\n */\nexport function generateRandomSlug(length: number = DEFAULT_SLUG_LENGTH): string {\n  const bytes = new Uint8Array(length);\n  crypto.getRandomValues(bytes);\n  let slug = '';\n  for (let i = 0; i < length; i++) {\n    slug += SLUG_ALPHABET[bytes[i]! % SLUG_ALPHABET.length];\n  }\n  return slug;\n}\n\n/** Check if a string is a valid slug format. */\nexport function isValidSlug(slug: string): boolean {\n  if (slug.length < 1 || slug.length > 32) return false;\n  return /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/.test(slug);\n}\n\n/** Normalize a slug to lowercase and trimmed. */\nexport function normalizeSlug(slug: string): string {\n  return slug.trim().toLowerCase();\n}\n","import type { UtmParams } from './types.js';\n\n/** All recognized UTM parameter keys. */\nconst UTM_KEYS = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'] as const;\n\n/** Append UTM parameters to a URL string. Existing UTM params on the URL are overwritten. */\nexport function appendUtm(url: string, utm: UtmParams): string {\n  const parsed = new URL(url);\n\n  for (const key of UTM_KEYS) {\n    const value = utm[key];\n    if (value !== undefined && value !== '') {\n      parsed.searchParams.set(key, value);\n    }\n  }\n\n  return parsed.toString();\n}\n\n/** Extract UTM parameters from a URL string. */\nexport function extractUtm(url: string): UtmParams {\n  const parsed = new URL(url);\n  const result: UtmParams = {};\n\n  for (const key of UTM_KEYS) {\n    const value = parsed.searchParams.get(key);\n    if (value !== null) {\n      result[key] = value;\n    }\n  }\n\n  return result;\n}\n\n/** Check if a UtmParams object has any non-empty values. */\nexport function hasUtm(utm: UtmParams | undefined): utm is UtmParams {\n  if (!utm) return false;\n  return UTM_KEYS.some((key) => utm[key] !== undefined && utm[key] !== '');\n}\n","import { MAX_SLUG_LENGTH, MAX_URL_LENGTH, MIN_SLUG_LENGTH, RESERVED_SLUGS } from './constants.js';\nimport type { ValidationResult } from './types.js';\n\n/** Allowed characters in a slug: lowercase alphanumeric plus hyphens. */\nconst SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;\n\n/** Validate a slug string. */\nexport function validateSlug(slug: string): ValidationResult {\n  if (slug.length < MIN_SLUG_LENGTH) {\n    return { valid: false, reason: `must be at least ${MIN_SLUG_LENGTH} characters` };\n  }\n  if (slug.length > MAX_SLUG_LENGTH) {\n    return { valid: false, reason: `must be at most ${MAX_SLUG_LENGTH} characters` };\n  }\n  if (!SLUG_PATTERN.test(slug)) {\n    return {\n      valid: false,\n      reason:\n        'must contain only lowercase letters, numbers, and hyphens (no leading/trailing hyphens)',\n    };\n  }\n  if (RESERVED_SLUGS.has(slug)) {\n    return { valid: false, reason: 'is a reserved slug' };\n  }\n  return { valid: true };\n}\n\n/** Validate a target URL. */\nexport function validateUrl(url: string): ValidationResult {\n  if (url.length === 0) {\n    return { valid: false, reason: 'URL cannot be empty' };\n  }\n  if (url.length > MAX_URL_LENGTH) {\n    return { valid: false, reason: `URL exceeds maximum length of ${MAX_URL_LENGTH} characters` };\n  }\n\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    return { valid: false, reason: 'not a valid URL' };\n  }\n\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    return { valid: false, reason: 'only http and https URLs are allowed' };\n  }\n\n  return { valid: true };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@clipr/core",
+  "version": "0.0.5",
+  "description": "Shared types, validation, slug generation, and utilities for clipr URL shortener",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "url-shortener",
+    "short-url",
+    "clipr",
+    "slug",
+    "validation",
+    "utm",
+    "sqids"
+  ],
+  "homepage": "https://github.com/hammadkhanxcm/clipr#readme",
+  "bugs": {
+    "url": "https://github.com/hammadkhanxcm/clipr/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hammadkhanxcm/clipr.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "sqids": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.0.0",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "Hammad Khan"
+}