npm - @clipr/worker - Versions diffs - 0.0.5 - Mend

@clipr/worker 0.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/.dev.vars +2 -0
package/.dev.vars.example +5 -0
package/CHANGELOG.md +29 -0
package/LICENSE +21 -0
package/dist/README.md +1 -0
package/dist/index.js +7139 -0
package/dist/index.js.map +8 -0
package/package.json +37 -0
package/src/crypto.ts +85 -0
package/src/index.ts +59 -0
package/src/kv-backend.test.ts +56 -0
package/src/kv-backend.ts +70 -0
package/src/kv.ts +164 -0
package/src/middleware/auth.ts +55 -0
package/src/routes/health.ts +5 -0
package/src/routes/import-export.ts +49 -0
package/src/routes/links.ts +98 -0
package/src/routes/password.ts +117 -0
package/src/routes/qr.ts +39 -0
package/src/routes/redirect.test.ts +127 -0
package/src/routes/redirect.ts +87 -0
package/src/routes/shorten.ts +85 -0
package/src/routes/stats.ts +20 -0
package/src/test-utils.ts +29 -0
package/src/types.ts +6 -0
package/src/utils/qr.ts +35 -0
package/tsconfig.json +9 -0
package/vitest.config.ts +7 -0
package/wrangler.toml +8 -0

package/src/routes/password.ts ADDED Viewed

@@ -0,0 +1,117 @@
+import { appendUtm, hasUtm } from '@clipr/core';
+import type { Context } from 'hono';
+import { verifyPassword } from '../crypto.js';
+import { getUrl } from '../kv.js';
+import type { Env } from '../types.js';
+/** Escape HTML special characters to prevent XSS. */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+/** Render a simple HTML password form. */
+function renderPasswordPage(code: string, error?: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Password Required - clipr</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      display: flex; justify-content: center; align-items: center;
+      min-height: 100vh; background: #f5f5f5; color: #333;
+    }
+    .card {
+      background: #fff; border-radius: 8px; padding: 2rem;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1); max-width: 400px; width: 100%;
+    }
+    h1 { font-size: 1.25rem; margin-bottom: 1rem; }
+    .error { color: #dc3545; font-size: 0.875rem; margin-bottom: 1rem; }
+    label { display: block; font-size: 0.875rem; margin-bottom: 0.5rem; font-weight: 500; }
+    input[type="password"] {
+      width: 100%; padding: 0.5rem 0.75rem; border: 1px solid #ddd;
+      border-radius: 4px; font-size: 1rem; margin-bottom: 1rem;
+    }
+    button {
+      width: 100%; padding: 0.625rem; background: #111; color: #fff;
+      border: none; border-radius: 4px; font-size: 1rem; cursor: pointer;
+    }
+    button:hover { background: #333; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>This link is password-protected</h1>
+    ${error ? `<p class="error">${escapeHtml(error)}</p>` : ''}
+    <form method="POST" action="/password/${escapeHtml(code)}">
+      <label for="password">Password</label>
+      <input type="password" id="password" name="password" required autofocus />
+      <button type="submit">Continue</button>
+    </form>
+  </div>
+</body>
+</html>`;
+}
+/** GET /password/:code — Render password form. */
+export async function handlePasswordPage(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.text('Not Found', 404);
+  }
+  const entry = await getUrl(c.env.URLS, code);
+  if (!entry) {
+    return c.text('Not Found', 404);
+  }
+  if (!entry.passwordHash) {
+    // Not password-protected, redirect directly
+    const target = hasUtm(entry.utm) ? appendUtm(entry.url, entry.utm) : entry.url;
+    return c.redirect(target, 301);
+  }
+  return c.html(renderPasswordPage(code));
+}
+/** POST /password/:code — Verify password and redirect or show error. */
+export async function handlePasswordVerify(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.text('Not Found', 404);
+  }
+  const entry = await getUrl(c.env.URLS, code);
+  if (!entry) {
+    return c.text('Not Found', 404);
+  }
+  if (!entry.passwordHash) {
+    const target = hasUtm(entry.utm) ? appendUtm(entry.url, entry.utm) : entry.url;
+    return c.redirect(target, 301);
+  }
+  // Parse form body
+  const body = await c.req.parseBody();
+  const password = body.password;
+  if (typeof password !== 'string' || !password) {
+    return c.html(renderPasswordPage(code, 'Password is required.'), 400);
+  }
+  const valid = await verifyPassword(password, entry.passwordHash);
+  if (!valid) {
+    return c.html(renderPasswordPage(code, 'Incorrect password. Please try again.'), 403);
+  }
+  // Password correct — redirect to the target
+  const target = hasUtm(entry.utm) ? appendUtm(entry.url, entry.utm) : entry.url;
+  return c.redirect(target, 301);
+}

package/src/routes/qr.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import type { Context } from 'hono';
+import { getUrl } from '../kv.js';
+import type { Env } from '../types.js';
+import { generateQr, type QrFormat } from '../utils/qr.js';
+/** GET /api/qr/:code — Generate a QR code for the short URL. */
+export async function handleQr(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.json({ error: 'Missing code parameter' }, 400);
+  }
+  // Verify the link exists
+  const entry = await getUrl(c.env.URLS, code);
+  if (!entry) {
+    return c.json({ error: `Link "${code}" not found` }, 404);
+  }
+  const format = (c.req.query('format') || 'svg') as QrFormat;
+  if (format !== 'svg' && format !== 'png') {
+    return c.json({ error: 'Invalid format, must be "svg" or "png"' }, 400);
+  }
+  const sizeStr = c.req.query('size');
+  const size = sizeStr ? parseInt(sizeStr, 10) : 256;
+  if (Number.isNaN(size) || size < 32 || size > 2048) {
+    return c.json({ error: 'Invalid size, must be between 32 and 2048' }, 400);
+  }
+  const shortUrl = `${c.env.BASE_URL}/${code}`;
+  const { data, contentType } = await generateQr(shortUrl, format, size);
+  return new Response(data as BodyInit, {
+    headers: {
+      'Content-Type': contentType,
+      'Cache-Control': 'public, max-age=3600',
+    },
+  });
+}

package/src/routes/redirect.test.ts ADDED Viewed

@@ -0,0 +1,127 @@
+import type { UrlEntry } from '@clipr/core';
+import { describe, expect, it } from 'vitest';
+import app from '../index.js';
+import { createMockKV } from '../test-utils.js';
+async function seedKV(kv: KVNamespace, entry: UrlEntry): Promise<void> {
+  // Use url: prefix to match kv.ts getUrl()
+  await kv.put(`url:${entry.slug}`, JSON.stringify(entry));
+  // Update the url index
+  const raw = await kv.get('_url_index', 'text');
+  const index: string[] = raw ? JSON.parse(raw) : [];
+  index.push(entry.slug);
+  await kv.put('_url_index', JSON.stringify(index));
+}
+function makeRequest(path: string, kv: KVNamespace): Promise<Response> {
+  return app.request(path, {}, { URLS: kv, API_TOKEN: 'test-token', BASE_URL: 'https://clpr.sh' });
+}
+describe('redirect route', () => {
+  it('redirects to the target URL (301)', async () => {
+    const kv = createMockKV();
+    await seedKV(kv, {
+      slug: 'test',
+      url: 'https://example.com',
+      createdAt: new Date().toISOString(),
+    });
+    const res = await makeRequest('/test', kv);
+    expect(res.status).toBe(301);
+    expect(res.headers.get('Location')).toBe('https://example.com');
+    expect(res.headers.get('Cache-Control')).toBe('public, max-age=300');
+  });
+  it('appends UTM params on redirect', async () => {
+    const kv = createMockKV();
+    await seedKV(kv, {
+      slug: 'utm',
+      url: 'https://example.com',
+      createdAt: new Date().toISOString(),
+      utm: { utm_source: 'twitter', utm_medium: 'social' },
+    });
+    const res = await makeRequest('/utm', kv);
+    expect(res.status).toBe(301);
+    const location = res.headers.get('Location')!;
+    const url = new URL(location);
+    expect(url.searchParams.get('utm_source')).toBe('twitter');
+    expect(url.searchParams.get('utm_medium')).toBe('social');
+  });
+  it('returns 404 for missing slugs', async () => {
+    const kv = createMockKV();
+    const res = await makeRequest('/missing', kv);
+    expect(res.status).toBe(404);
+  });
+  it('returns 410 for expired links', async () => {
+    const kv = createMockKV();
+    await seedKV(kv, {
+      slug: 'old',
+      url: 'https://example.com',
+      createdAt: new Date().toISOString(),
+      expiresAt: '2020-01-01T00:00:00Z',
+    });
+    const res = await makeRequest('/old', kv);
+    expect(res.status).toBe(410);
+  });
+  it('redirects non-expired links with expiresAt', async () => {
+    const kv = createMockKV();
+    const future = new Date(Date.now() + 86400000).toISOString();
+    await seedKV(kv, {
+      slug: 'future',
+      url: 'https://example.com',
+      createdAt: new Date().toISOString(),
+      expiresAt: future,
+    });
+    const res = await makeRequest('/future', kv);
+    expect(res.status).toBe(301);
+  });
+});
+describe('health route', () => {
+  it('returns 200 with status ok', async () => {
+    const kv = createMockKV();
+    const res = await makeRequest('/health', kv);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe('ok');
+  });
+});
+describe('404 handler', () => {
+  it('returns 401 for deep paths without auth', async () => {
+    const kv = createMockKV();
+    const res = await makeRequest('/some/deep/path', kv);
+    // Deep paths are not public routes, so auth middleware blocks them
+    expect(res.status).toBe(401);
+  });
+  it('returns 404 for non-existent single-segment slugs', async () => {
+    const kv = createMockKV();
+    const res = await makeRequest('/nonexistent', kv);
+    expect(res.status).toBe(404);
+  });
+});
+describe('API auth', () => {
+  it('returns 401 for API routes without token', async () => {
+    const kv = createMockKV();
+    const res = app.request('/api/links', {}, { URLS: kv, API_TOKEN: 'secret', BASE_URL: '' });
+    expect((await res).status).toBe(401);
+  });
+  it('allows API routes with valid token', async () => {
+    const kv = createMockKV();
+    const res = await app.request(
+      '/api/links',
+      { headers: { Authorization: 'Bearer secret' } },
+      { URLS: kv, API_TOKEN: 'secret', BASE_URL: '' },
+    );
+    expect(res.status).toBe(200);
+  });
+});

package/src/routes/redirect.ts ADDED Viewed

@@ -0,0 +1,87 @@
+import { appendUtm, hasUtm } from '@clipr/core';
+import type { Context } from 'hono';
+import { getUrl, incrementStat } from '../kv.js';
+import type { Env } from '../types.js';
+/** Check if a URL entry has expired. */
+function isExpired(expiresAt: string | undefined): boolean {
+  if (!expiresAt) return false;
+  return new Date(expiresAt).getTime() < Date.now();
+}
+/** Extract a simple device type from User-Agent. */
+function parseDevice(ua: string | undefined): string {
+  if (!ua) return 'unknown';
+  const lower = ua.toLowerCase();
+  if (lower.includes('mobile') || lower.includes('android') || lower.includes('iphone'))
+    return 'mobile';
+  if (lower.includes('tablet') || lower.includes('ipad')) return 'tablet';
+  return 'desktop';
+}
+/** Extract referrer domain from Referer header. */
+function parseReferrer(referer: string | undefined): string {
+  if (!referer) return 'direct';
+  try {
+    return new URL(referer).hostname;
+  } catch {
+    return 'unknown';
+  }
+}
+export async function handleRedirect(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const slug = c.req.param('slug');
+  if (!slug) {
+    return c.text('Not Found', 404);
+  }
+  const entry = await getUrl(c.env.URLS, slug);
+  if (!entry) {
+    return c.text('Not Found', 404);
+  }
+  if (isExpired(entry.expiresAt)) {
+    return c.text('This link has expired', 410);
+  }
+  // Password-protected links redirect to the password page
+  if (entry.passwordHash) {
+    return c.redirect(`/password/${slug}`, 302);
+  }
+  const target = hasUtm(entry.utm) ? appendUtm(entry.url, entry.utm) : entry.url;
+  // Non-blocking analytics via waitUntil
+  let ctx: { waitUntil: (p: Promise<unknown>) => void } | undefined;
+  try {
+    ctx = c.executionCtx;
+  } catch {
+    // executionCtx not available in test environment
+  }
+  if (ctx && 'waitUntil' in ctx) {
+    const kv = c.env.URLS;
+    const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+    const country = c.req.header('cf-ipcountry') || 'unknown';
+    const device = parseDevice(c.req.header('user-agent'));
+    const referrer = parseReferrer(c.req.header('referer'));
+    ctx.waitUntil(
+      Promise.all([
+        incrementStat(kv, slug, 'total'),
+        incrementStat(kv, slug, 'daily', date),
+        incrementStat(kv, slug, 'geo', country),
+        incrementStat(kv, slug, 'device', device),
+        incrementStat(kv, slug, 'referrer', referrer),
+      ]),
+    );
+  }
+  return new Response(null, {
+    status: 301,
+    headers: {
+      Location: target,
+      'Cache-Control': 'public, max-age=300',
+    },
+  });
+}

package/src/routes/shorten.ts ADDED Viewed

@@ -0,0 +1,85 @@
+import type { ShortUrl, UtmParams } from '@clipr/core';
+import { generateSlug, validateSlug, validateUrl } from '@clipr/core';
+import type { Context } from 'hono';
+import { hashPassword } from '../crypto.js';
+import { getUrl, incrementCounter, putUrl } from '../kv.js';
+import type { Env } from '../types.js';
+interface ShortenBody {
+  url: string;
+  slug?: string;
+  tags?: string[];
+  expiresAt?: string;
+  password?: string;
+  description?: string;
+  utm?: UtmParams;
+  ogTitle?: string;
+  ogDescription?: string;
+  ogImage?: string;
+}
+/** POST /api/shorten — Create a new short URL. */
+export async function handleShorten(c: Context<{ Bindings: Env }>): Promise<Response> {
+  let body: ShortenBody;
+  try {
+    body = await c.req.json<ShortenBody>();
+  } catch {
+    return c.json({ error: 'Invalid JSON body' }, 400);
+  }
+  if (!body.url) {
+    return c.json({ error: 'Missing required field: url' }, 400);
+  }
+  // Validate URL
+  const urlResult = validateUrl(body.url);
+  if (!urlResult.valid) {
+    return c.json({ error: `Invalid URL: ${urlResult.reason}` }, 400);
+  }
+  // Determine slug
+  let slug: string;
+  if (body.slug) {
+    const slugResult = validateSlug(body.slug);
+    if (!slugResult.valid) {
+      return c.json({ error: `Invalid slug: ${slugResult.reason}` }, 400);
+    }
+    slug = body.slug;
+    // Check for conflicts
+    const existing = await getUrl(c.env.URLS, slug);
+    if (existing) {
+      return c.json({ error: `Slug "${slug}" already exists` }, 409);
+    }
+  } else {
+    // Auto-generate slug from counter
+    const counter = await incrementCounter(c.env.URLS);
+    slug = generateSlug(counter);
+  }
+  // Hash password if provided
+  let passwordHash: string | undefined;
+  if (body.password) {
+    passwordHash = await hashPassword(body.password);
+  }
+  const now = new Date().toISOString();
+  const entry: ShortUrl = {
+    slug,
+    url: body.url,
+    createdAt: now,
+    ...(body.expiresAt && { expiresAt: body.expiresAt }),
+    ...(body.description && { description: body.description }),
+    ...(body.tags && { tags: body.tags }),
+    ...(body.utm && { utm: body.utm }),
+    ...(passwordHash && { passwordHash }),
+    ...(body.ogTitle && { ogTitle: body.ogTitle }),
+    ...(body.ogDescription && { ogDescription: body.ogDescription }),
+    ...(body.ogImage && { ogImage: body.ogImage }),
+  };
+  await putUrl(c.env.URLS, slug, entry);
+  const shortUrl = `${c.env.BASE_URL}/${slug}`;
+  return c.json({ slug, shortUrl, url: body.url }, 201);
+}

package/src/routes/stats.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import type { Context } from 'hono';
+import { getStats, getUrl } from '../kv.js';
+import type { Env } from '../types.js';
+/** GET /api/stats/:code — Returns LinkStats JSON for a link. */
+export async function handleStats(c: Context<{ Bindings: Env }>): Promise<Response> {
+  const code = c.req.param('code');
+  if (!code) {
+    return c.json({ error: 'Missing code parameter' }, 400);
+  }
+  // Verify the link exists
+  const entry = await getUrl(c.env.URLS, code);
+  if (!entry) {
+    return c.json({ error: `Link "${code}" not found` }, 404);
+  }
+  const stats = await getStats(c.env.URLS, code);
+  return c.json({ code, ...stats });
+}

package/src/test-utils.ts ADDED Viewed

@@ -0,0 +1,29 @@
+/** In-memory KVNamespace mock for testing. */
+export function createMockKV(): KVNamespace {
+  const store = new Map<string, string>();
+  return {
+    get(key: string, _opts?: unknown): Promise<string | null> {
+      return Promise.resolve(store.get(key) ?? null);
+    },
+    put(key: string, value: string): Promise<void> {
+      store.set(key, value);
+      return Promise.resolve();
+    },
+    delete(key: string): Promise<void> {
+      store.delete(key);
+      return Promise.resolve();
+    },
+    list(): Promise<KVNamespaceListResult<unknown, string>> {
+      const keys = [...store.keys()].map((name) => ({ name }));
+      return Promise.resolve({
+        keys,
+        list_complete: true,
+        cacheStatus: null,
+      } as KVNamespaceListResult<unknown, string>);
+    },
+    getWithMetadata(): Promise<KVNamespaceGetWithMetadataResult<string, unknown>> {
+      return Promise.resolve({ value: null, metadata: null, cacheStatus: null });
+    },
+  } as unknown as KVNamespace;
+}

package/src/types.ts ADDED Viewed

@@ -0,0 +1,6 @@
+/** Cloudflare Worker environment bindings. */
+export interface Env {
+  URLS: KVNamespace;
+  API_TOKEN: string;
+  BASE_URL: string;
+}

package/src/utils/qr.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import QRCode from 'qrcode';
+export type QrFormat = 'svg' | 'png';
+/**
+ * Generate a QR code for the given text.
+ * @param text - The content to encode (typically a URL).
+ * @param format - Output format: 'svg' or 'png'.
+ * @param size - Width/height in pixels (for PNG) or module count hint.
+ * @returns The QR code as a string (SVG) or Buffer (PNG).
+ */
+export async function generateQr(
+  text: string,
+  format: QrFormat = 'svg',
+  size: number = 256,
+): Promise<{ data: string | Buffer; contentType: string }> {
+  if (format === 'svg') {
+    const svg = await QRCode.toString(text, {
+      type: 'svg',
+      width: size,
+      margin: 2,
+    });
+    return { data: svg, contentType: 'image/svg+xml' };
+  }
+  // PNG format
+  const dataUrl = await QRCode.toDataURL(text, {
+    width: size,
+    margin: 2,
+  });
+  // Strip the data:image/png;base64, prefix and decode
+  const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+  const buffer = Uint8Array.from(atob(base64), (ch) => ch.charCodeAt(0));
+  return { data: buffer as unknown as Buffer, contentType: 'image/png' };
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tooling/typescript/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src"]
+}

package/vitest.config.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+  },
+});

package/wrangler.toml ADDED Viewed

@@ -0,0 +1,8 @@
+name = "clipr"
+main = "src/index.ts"
+compatibility_date = "2025-03-30"
+compatibility_flags = ["nodejs_compat"]
+[[kv_namespaces]]
+binding = "URLS"
+id = "1ed1615bdd234d23887b3c58b42b3dc4"