@hasna/shortlinks 0.1.13 → 0.1.15

package/cloudflare/shortlinks.js

@@ -6,25 +6,32 @@ export default {
     }
 
     const incoming = new URL(request.url);
+    const proxyTo = (targetOrigin, marker) => {
+      const upstream = new URL(incoming.pathname + incoming.search, targetOrigin);
+      const headers = new Headers(request.headers);
+      headers.set("x-forwarded-host", incoming.host);
+      headers.set("x-shortlinks-worker", marker);
+
+      return fetch(upstream.toString(), {
+        method: request.method,
+        headers,
+        body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+        redirect: "manual"
+      });
+    };
+
     const reserved = (env.SHORTLINKS_RESERVED_PATH_PREFIXES || "a")
       .split(",")
       .map((value) => value.trim().toLowerCase())
       .filter(Boolean);
     const firstSegment = decodeURIComponent(incoming.pathname.replace(/^\/+/, "").split("/")[0] || "").toLowerCase();
     if (firstSegment && reserved.includes(firstSegment)) {
+      if (env.ATTACHMENTS_ORIGIN) {
+        return proxyTo(env.ATTACHMENTS_ORIGIN, "attachments");
+      }
       return new Response("Reserved path prefix", { status: 404 });
     }
 
-    const upstream = new URL(incoming.pathname + incoming.search, origin);
-    const headers = new Headers(request.headers);
-    headers.set("x-forwarded-host", incoming.host);
-    headers.set("x-shortlinks-worker", "cloudflare");
-
-    return fetch(upstream.toString(), {
-      method: request.method,
-      headers,
-      body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
-      redirect: "manual"
-    });
+    return proxyTo(origin, "cloudflare");
   }
 };

package/cloudflare/wrangler.example.toml

@@ -4,4 +4,5 @@ compatibility_date = "2026-05-01"
 
 [vars]
 SHORTLINKS_ORIGIN = "https://shortlinks.example.com"
+ATTACHMENTS_ORIGIN = ""
 SHORTLINKS_RESERVED_PATH_PREFIXES = "a"

package/dist/api-client.d.ts

@@ -0,0 +1,30 @@
+import type { AddDomainInput, CreateLinkInput, Domain, Link, LinkStats } from "./types.js";
+export interface ShortlinksApiClientOptions {
+    baseUrl?: string;
+    token?: string;
+}
+export declare class ShortlinksApiClient {
+    private readonly options;
+    constructor(options?: ShortlinksApiClientOptions);
+    private url;
+    private headers;
+    totalStats(): Promise<{
+        domains: number;
+        links: number;
+        clicks: number;
+    }>;
+    createLink(input: CreateLinkInput): Promise<Link>;
+    listLinks(options?: {
+        domain?: string;
+        activeOnly?: boolean;
+        limit?: number;
+    }): Promise<Link[]>;
+    getLink(domainOrSlug: string, maybeSlug?: string): Promise<Link | null>;
+    setLinkActive(domainOrSlug: string, maybeSlugOrActive: string | boolean, maybeActive?: boolean): Promise<Link>;
+    deleteLink(domainOrSlug: string, maybeSlug?: string): Promise<Link>;
+    getStats(domainOrSlug: string, maybeSlug?: string): Promise<LinkStats>;
+    addDomain(input: AddDomainInput): Promise<Domain>;
+    listDomains(): Promise<Domain[]>;
+    getDomain(hostname: string): Promise<Domain | null>;
+    close(): Promise<void>;
+}

package/dist/cli/index.js

@@ -2121,17 +2121,31 @@ function saveConfig(config) {
 `);
 }
 function updateConfig(patch) {
+  const current = loadConfig();
   const next = {
-    ...loadConfig(),
+    ...current,
     ...patch,
+    api: {
+      ...current.api,
+      ...patch.api
+    },
     cloudflare: {
-      ...loadConfig().cloudflare,
+      ...current.cloudflare,
       ...patch.cloudflare
     }
   };
   saveConfig(next);
   return next;
 }
+function getApiBaseUrl(config = loadConfig()) {
+  const baseUrl = process.env.SHORTLINKS_API_URL || process.env.HASNA_SHORTLINKS_API_URL || config.api?.baseUrl || "";
+  return baseUrl ? baseUrl.replace(/\/+$/, "") : null;
+}
+function getApiToken(config = loadConfig()) {
+  const envName = config.api?.tokenEnv || "SHORTLINKS_API_TOKEN";
+  const token = process.env[envName] || process.env.SHORTLINKS_API_TOKEN || process.env.HASNA_SHORTLINKS_API_TOKEN || config.api?.token || "";
+  return token || null;
+}
 function normalizeHostname(input) {
   const raw = input.trim().toLowerCase();
   if (!raw)
@@ -9473,6 +9487,156 @@ class PgShortlinksStore {
 // src/cli/index.ts
 init_config();
 
+// src/api-client.ts
+init_config();
+function normalizeBaseUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+function requireBaseUrl(options) {
+  const baseUrl = options.baseUrl || getApiBaseUrl(loadConfig());
+  if (!baseUrl) {
+    throw new Error("Shortlinks API URL is not configured. Run `shortlinks config set api-url <url>` or set SHORTLINKS_API_URL.");
+  }
+  return normalizeBaseUrl(baseUrl);
+}
+function requireToken(options) {
+  const token = options.token || getApiToken(loadConfig());
+  if (!token) {
+    throw new Error("Shortlinks API token is not configured. Set SHORTLINKS_API_TOKEN or run `shortlinks config set api-token-env <name>`.");
+  }
+  return token;
+}
+async function readJson(response) {
+  const text = await response.text();
+  let parsed = {};
+  if (text) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = { error: text };
+    }
+  }
+  if (!response.ok) {
+    const message = parsed && typeof parsed === "object" && "error" in parsed ? String(parsed.error) : `HTTP ${response.status}`;
+    throw new Error(message);
+  }
+  return parsed;
+}
+
+class ShortlinksApiClient {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  url(path, query) {
+    const url = new URL(`${requireBaseUrl(this.options)}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== undefined && value !== "")
+        url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  headers(extra) {
+    return {
+      authorization: `Bearer ${requireToken(this.options)}`,
+      ...extra ?? {}
+    };
+  }
+  async totalStats() {
+    const response = await fetch(this.url("/stats"), { headers: this.headers() });
+    return readJson(response);
+  }
+  async createLink(input) {
+    const response = await fetch(this.url("/links"), {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify({
+        destination_url: input.destinationUrl,
+        domain: input.domain,
+        slug: input.slug,
+        title: input.title,
+        expires_at: input.expiresAt,
+        length: input.slugLength
+      })
+    });
+    return readJson(response);
+  }
+  async listLinks(options = {}) {
+    const response = await fetch(this.url("/links", {
+      domain: options.domain,
+      active: options.activeOnly,
+      limit: options.limit
+    }), { headers: this.headers() });
+    return readJson(response);
+  }
+  async getLink(domainOrSlug, maybeSlug) {
+    const slug = maybeSlug ?? domainOrSlug;
+    const response = await fetch(this.url(`/links/${encodeURIComponent(slug)}`, {
+      domain: maybeSlug ? domainOrSlug : undefined
+    }), { headers: this.headers() });
+    if (response.status === 404)
+      return null;
+    return readJson(response);
+  }
+  async setLinkActive(domainOrSlug, maybeSlugOrActive, maybeActive) {
+    const hasDomain = typeof maybeSlugOrActive === "string";
+    const slug = hasDomain ? maybeSlugOrActive : domainOrSlug;
+    const active = hasDomain ? Boolean(maybeActive) : Boolean(maybeSlugOrActive);
+    const response = await fetch(this.url(`/links/${encodeURIComponent(slug)}/active`, {
+      domain: hasDomain ? domainOrSlug : undefined
+    }), {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify({ active })
+    });
+    return readJson(response);
+  }
+  async deleteLink(domainOrSlug, maybeSlug) {
+    const slug = maybeSlug ?? domainOrSlug;
+    const response = await fetch(this.url(`/links/${encodeURIComponent(slug)}`, {
+      domain: maybeSlug ? domainOrSlug : undefined
+    }), {
+      method: "DELETE",
+      headers: this.headers()
+    });
+    return readJson(response);
+  }
+  async getStats(domainOrSlug, maybeSlug) {
+    const slug = maybeSlug ?? domainOrSlug;
+    const response = await fetch(this.url(`/stats/${encodeURIComponent(slug)}`, {
+      domain: maybeSlug ? domainOrSlug : undefined
+    }), { headers: this.headers() });
+    return readJson(response);
+  }
+  async addDomain(input) {
+    const response = await fetch(this.url("/domains"), {
+      method: "POST",
+      headers: this.headers({ "content-type": "application/json" }),
+      body: JSON.stringify({
+        hostname: input.hostname,
+        provider: input.provider,
+        default_domain: input.defaultDomain,
+        origin_url: input.originUrl,
+        notes: input.notes
+      })
+    });
+    return readJson(response);
+  }
+  async listDomains() {
+    const response = await fetch(this.url("/domains"), { headers: this.headers() });
+    return readJson(response);
+  }
+  async getDomain(hostname2) {
+    const response = await fetch(this.url(`/domains/${encodeURIComponent(hostname2)}`), { headers: this.headers() });
+    if (response.status === 404)
+      return null;
+    return readJson(response);
+  }
+  async close() {
+    return;
+  }
+}
+
 // src/server.ts
 function json(data, status = 200) {
   return new Response(JSON.stringify(data, null, 2), {
@@ -9480,6 +9644,120 @@ function json(data, status = 200) {
     headers: { "content-type": "application/json; charset=utf-8" }
   });
 }
+function apiToken(options) {
+  return options.apiToken || process.env.SHORTLINKS_API_TOKEN || process.env.HASNA_SHORTLINKS_API_TOKEN || null;
+}
+function requestToken(request) {
+  const auth = request.headers.get("authorization") || "";
+  const bearer = auth.toLowerCase().startsWith("bearer ") ? auth.slice(7).trim() : "";
+  return bearer || request.headers.get("x-shortlinks-token") || request.headers.get("x-api-key");
+}
+function isAuthorized(request, options) {
+  const token = apiToken(options);
+  if (!token)
+    return true;
+  return requestToken(request) === token;
+}
+async function readJsonBody(request) {
+  try {
+    const parsed = await request.json();
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function requireMethod(store, method) {
+  const fn = store[method];
+  if (typeof fn !== "function")
+    throw new Error(`Store does not support ${String(method)}.`);
+  return fn.bind(store);
+}
+async function handleApi(request, apiPath, store, options) {
+  if (apiPath === "/health") {
+    return json({ ok: true, service: "shortlinks", api_auth_required: Boolean(apiToken(options)), stats: await store.totalStats() });
+  }
+  if (!isAuthorized(request, options))
+    return json({ error: "Unauthorized" }, 401);
+  const url = new URL(request.url);
+  const segments = apiPath.replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+  try {
+    if (apiPath === "/links" && request.method === "GET") {
+      const listLinks = requireMethod(store, "listLinks");
+      return json(await listLinks({
+        domain: url.searchParams.get("domain") || undefined,
+        activeOnly: url.searchParams.get("active") === "true",
+        limit: Number(url.searchParams.get("limit") || "100")
+      }));
+    }
+    if (apiPath === "/links" && request.method === "POST") {
+      const body = await readJsonBody(request);
+      const destinationUrl = String(body.destination_url || body.url || "");
+      if (!destinationUrl)
+        return json({ error: "destination_url is required" }, 400);
+      const createLink = requireMethod(store, "createLink");
+      return json(await createLink({
+        destinationUrl,
+        domain: typeof body.domain === "string" ? body.domain : undefined,
+        slug: typeof body.slug === "string" ? body.slug : undefined,
+        title: typeof body.title === "string" ? body.title : undefined,
+        expiresAt: typeof body.expires_at === "string" ? body.expires_at : typeof body.expires === "string" ? body.expires : undefined,
+        slugLength: typeof body.length === "number" ? body.length : undefined
+      }), 201);
+    }
+    if (segments[0] === "links" && segments[1] && request.method === "GET") {
+      const getLink = requireMethod(store, "getLink");
+      const domain = url.searchParams.get("domain") || undefined;
+      const link = domain ? await getLink(domain, segments[1]) : await getLink(segments[1]);
+      return link ? json(link) : json({ error: "Link not found." }, 404);
+    }
+    if (segments[0] === "links" && segments[1] && request.method === "DELETE") {
+      const deleteLink = requireMethod(store, "deleteLink");
+      const domain = url.searchParams.get("domain") || undefined;
+      return json(domain ? await deleteLink(domain, segments[1]) : await deleteLink(segments[1]));
+    }
+    if (segments[0] === "links" && segments[1] && segments[2] === "active" && request.method === "POST") {
+      const body = await readJsonBody(request);
+      const setLinkActive = requireMethod(store, "setLinkActive");
+      const domain = url.searchParams.get("domain") || undefined;
+      const active = Boolean(body.active);
+      return json(domain ? await setLinkActive(domain, segments[1], active) : await setLinkActive(segments[1], active));
+    }
+    if (apiPath === "/stats" && request.method === "GET") {
+      return json(await store.totalStats());
+    }
+    if (segments[0] === "stats" && segments[1] && request.method === "GET") {
+      const getStats = requireMethod(store, "getStats");
+      const domain = url.searchParams.get("domain") || undefined;
+      return json(domain ? await getStats(domain, segments[1]) : await getStats(segments[1]));
+    }
+    if (apiPath === "/domains" && request.method === "GET") {
+      const listDomains = requireMethod(store, "listDomains");
+      return json(await listDomains());
+    }
+    if (apiPath === "/domains" && request.method === "POST") {
+      const body = await readJsonBody(request);
+      const hostname2 = String(body.hostname || "");
+      if (!hostname2)
+        return json({ error: "hostname is required" }, 400);
+      const addDomain = requireMethod(store, "addDomain");
+      return json(await addDomain({
+        hostname: hostname2,
+        provider: typeof body.provider === "string" ? body.provider : "manual",
+        defaultDomain: Boolean(body.default_domain || body.default),
+        originUrl: typeof body.origin_url === "string" ? body.origin_url : undefined,
+        notes: typeof body.notes === "string" ? body.notes : undefined
+      }), 201);
+    }
+    if (segments[0] === "domains" && segments[1] && request.method === "GET") {
+      const getDomain = requireMethod(store, "getDomain");
+      const domain = await getDomain(segments[1]);
+      return domain ? json(domain) : json({ error: "Domain not found." }, 404);
+    }
+  } catch (error) {
+    return json({ error: error instanceof Error ? error.message : String(error) }, 400);
+  }
+  return json({ error: "Not found." }, 404);
+}
 function getHost(request, fallback) {
   const forwarded = request.headers.get("x-forwarded-host");
   const host = forwarded || request.headers.get("host") || fallback || "";
@@ -9498,8 +9776,13 @@ function createShortlinksHandler(options = {}) {
   const store = options.store || new ShortlinksStore(options.dbPath);
   const redirectStatus = options.redirectStatus || 302;
   const reservedPathPrefixes = new Set((options.reservedPathPrefixes ?? ["a"]).map((prefix) => prefix.toLowerCase()));
+  const apiPathPrefix = (options.apiPathPrefix || process.env.SHORTLINKS_API_PATH_PREFIX || "/api").replace(/\/+$/, "") || "/api";
   return async (request) => {
     const url = new URL(request.url);
+    if (url.pathname === apiPathPrefix || url.pathname.startsWith(`${apiPathPrefix}/`)) {
+      const apiPath = url.pathname.slice(apiPathPrefix.length) || "/";
+      return handleApi(request, apiPath, store, options);
+    }
     if (url.pathname === "/healthz") {
       return json({ ok: true, service: "shortlinks", stats: await store.totalStats() });
     }
@@ -9585,26 +9868,33 @@ function generateWorkerScript() {
     }
 
     const incoming = new URL(request.url);
+    const proxyTo = (targetOrigin, marker) => {
+      const upstream = new URL(incoming.pathname + incoming.search, targetOrigin);
+      const headers = new Headers(request.headers);
+      headers.set("x-forwarded-host", incoming.host);
+      headers.set("x-shortlinks-worker", marker);
+
+      return fetch(upstream.toString(), {
+        method: request.method,
+        headers,
+        body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+        redirect: "manual"
+      });
+    };
+
     const reserved = (env.SHORTLINKS_RESERVED_PATH_PREFIXES || "a")
       .split(",")
       .map((value) => value.trim().toLowerCase())
       .filter(Boolean);
     const firstSegment = decodeURIComponent(incoming.pathname.replace(/^\\/+/, "").split("/")[0] || "").toLowerCase();
     if (firstSegment && reserved.includes(firstSegment)) {
+      if (env.ATTACHMENTS_ORIGIN) {
+        return proxyTo(env.ATTACHMENTS_ORIGIN, "attachments");
+      }
       return new Response("Reserved path prefix", { status: 404 });
     }
 
-    const upstream = new URL(incoming.pathname + incoming.search, origin);
-    const headers = new Headers(request.headers);
-    headers.set("x-forwarded-host", incoming.host);
-    headers.set("x-shortlinks-worker", "cloudflare");
-
-    return fetch(upstream.toString(), {
-      method: request.method,
-      headers,
-      body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
-      redirect: "manual"
-    });
+    return proxyTo(origin, "cloudflare");
   }
 };
 `;
@@ -9622,14 +9912,15 @@ compatibility_date = "2026-05-01"
 
 [vars]
 SHORTLINKS_ORIGIN = "${options.origin || "https://shortlinks.example.com"}"
+ATTACHMENTS_ORIGIN = "${options.attachmentsOrigin || ""}"
 SHORTLINKS_RESERVED_PATH_PREFIXES = "a"
 `);
   return { workerPath, wranglerPath };
 }
 function cloudflareAuthHeaders(token) {
-  const apiToken = token || process.env.CLOUDFLARE_API_TOKEN;
-  if (apiToken)
-    return { authorization: `Bearer ${apiToken}` };
+  const apiToken2 = token || process.env.CLOUDFLARE_API_TOKEN;
+  if (apiToken2)
+    return { authorization: `Bearer ${apiToken2}` };
   const apiKey = process.env.CLOUDFLARE_API_KEY;
   const email = process.env.CLOUDFLARE_EMAIL;
   if (apiKey && email) {
@@ -9815,13 +10106,19 @@ function withStore(fn) {
 }
 function storeMode() {
   const opts = program2.opts();
-  const value = String(opts.remote ? "remote" : opts.store || process.env.SHORTLINKS_STORE || "local").toLowerCase();
-  if (value !== "local" && value !== "remote")
+  const config = loadConfig();
+  const value = String(opts.remote ? "remote" : opts.store || process.env.SHORTLINKS_STORE || config.mode || "local").toLowerCase();
+  if (value !== "local" && value !== "remote" && value !== "api")
     throw new Error(`Unknown store mode: ${value}`);
   return value;
 }
 async function withRuntimeStore(fn) {
-  if (storeMode() === "remote") {
+  const mode = storeMode();
+  if (mode === "api") {
+    const store2 = new ShortlinksApiClient({ baseUrl: program2.opts().apiUrl });
+    return await fn(store2);
+  }
+  if (mode === "remote") {
     const store2 = await PgShortlinksStore.fromStorage("shortlinks");
     try {
       return await fn(store2);
@@ -9843,7 +10140,7 @@ function commandExists(command) {
   const result = spawnSync3("which", [command], { encoding: "utf-8" });
   return result.status === 0;
 }
-program2.name("shortlinks").description("CLI-only shortlink manager with custom domains, click tracking, Cloudflare helpers, and storage sync").version(getPackageVersion()).option("--db <path>", "SQLite database path").option("--store <mode>", "Data store mode: remote or local", process.env.SHORTLINKS_STORE || "local").addOption(new Option("--remote", "Use the shortlinks PostgreSQL storage database directly")).option("-j, --json", "Output JSON for agents and scripts");
+program2.name("shortlinks").description("CLI-only shortlink manager with custom domains, click tracking, Cloudflare helpers, and storage sync").version(getPackageVersion()).option("--db <path>", "SQLite database path").option("--store <mode>", "Data store mode: local, remote, or api", process.env.SHORTLINKS_STORE || loadConfig().mode || "local").option("--api-url <url>", "Shortlinks HTTP API base URL").addOption(new Option("--remote", "Use the shortlinks PostgreSQL storage database directly")).option("-j, --json", "Output JSON for agents and scripts");
 program2.command("init").description("Initialize local shortlinks storage").option("--domain <hostname>", "Add a default shortlink domain").option("--public-base-url <url>", "Public URL base for generated links").option("-j, --json", "Output JSON").action(async (opts) => {
   try {
     const result = await withRuntimeStore(async (store) => {
@@ -9883,19 +10180,42 @@ program2.command("init").description("Initialize local shortlinks storage").opti
 });
 var configCmd = program2.command("config").description("View and update local config");
 configCmd.command("show").description("Show local config").option("-j, --json", "Output JSON").action((opts) => {
-  const data = { path: getConfigPath(), config: loadConfig() };
+  const config = loadConfig();
+  const data = {
+    path: getConfigPath(),
+    config: {
+      ...config,
+      api: config.api ? { ...config.api, token: config.api.token ? "****" : "" } : undefined
+    }
+  };
   print2(data, opts, () => console.log(JSON.stringify(data, null, 2)));
 });
-configCmd.command("set <key> <value>").description("Set config value: default-domain, public-base-url, cloudflare-account-id, cloudflare-worker-name, cloudflare-origin").option("-j, --json", "Output JSON").action((key, value, opts) => {
+configCmd.command("set <key> <value>").description("Set config value: mode, default-domain, public-base-url, api-url, api-token, api-token-env, cloudflare-account-id, cloudflare-worker-name, cloudflare-origin").option("-j, --json", "Output JSON").action((key, value, opts) => {
   try {
     let config = loadConfig();
     switch (key) {
+      case "mode": {
+        const mode = value.toLowerCase();
+        if (mode !== "local" && mode !== "remote" && mode !== "api")
+          throw new Error("mode must be local, remote, or api");
+        config = updateConfig({ mode });
+        break;
+      }
       case "default-domain":
         config = updateConfig({ defaultDomain: value, publicBaseUrl: config.publicBaseUrl || `https://${value}` });
         break;
       case "public-base-url":
         config = updateConfig({ publicBaseUrl: value });
         break;
+      case "api-url":
+        config = updateConfig({ api: { baseUrl: value.replace(/\/+$/, "") } });
+        break;
+      case "api-token":
+        config = updateConfig({ api: { token: value } });
+        break;
+      case "api-token-env":
+        config = updateConfig({ api: { tokenEnv: value } });
+        break;
       case "cloudflare-account-id":
         config = updateConfig({ cloudflare: { accountId: value } });
         break;
@@ -9908,7 +10228,11 @@ configCmd.command("set <key> <value>").description("Set config value: default-do
       default:
         throw new Error(`Unknown config key: ${key}`);
     }
-    print2({ path: getConfigPath(), config }, opts, () => console.log(source_default.green(`Set ${key}.`)));
+    const masked = {
+      ...config,
+      api: config.api ? { ...config.api, token: config.api.token ? "****" : "" } : undefined
+    };
+    print2({ path: getConfigPath(), config: masked }, opts, () => console.log(source_default.green(`Set ${key}.`)));
   } catch (error) {
     handleError(error);
   }
@@ -10103,7 +10427,7 @@ program2.command("stats [slug]").description("Show overall stats or stats for a
     handleError(error);
   }
 });
-program2.command("serve").description("Run the redirect server that records clicks").option("--host <host>", "Bind host", "127.0.0.1").option("--port <port>", "Port", "8787").option("--default-host <hostname>", "Fallback host if the request has no Host header").option("--remote", "Serve directly from the shortlinks PostgreSQL storage database").addOption(new Option("--cloud", "Deprecated alias for --remote").hideHelp()).action(async (opts) => {
+program2.command("serve").description("Run the redirect server that records clicks").option("--host <host>", "Bind host", "127.0.0.1").option("--port <port>", "Port", "8787").option("--default-host <hostname>", "Fallback host if the request has no Host header").option("--api-path-prefix <path>", "Admin API path prefix", process.env.SHORTLINKS_API_PATH_PREFIX || "/api").option("--remote", "Serve directly from the shortlinks PostgreSQL storage database").addOption(new Option("--cloud", "Deprecated alias for --remote").hideHelp()).action(async (opts) => {
   try {
     const store = opts.remote || opts.cloud || storeMode() === "remote" ? await PgShortlinksStore.fromStorage("shortlinks") : undefined;
     const server = serveShortlinks({
@@ -10111,7 +10435,8 @@ program2.command("serve").description("Run the redirect server that records clic
       dbPath: program2.opts().db,
       host: opts.host,
       port: Number(opts.port),
-      defaultHost: opts.defaultHost
+      defaultHost: opts.defaultHost,
+      apiPathPrefix: opts.apiPathPrefix
     });
     const mode = store ? "remote" : "local";
     console.log(source_default.green(`shortlinks redirect server listening on http://${server.hostname}:${server.port} (${mode})`));
@@ -10134,9 +10459,14 @@ cfCmd.command("plan <hostname>").description("Print the Cloudflare setup plan").
     handleError(error);
   }
 });
-cfCmd.command("worker").description("Write Cloudflare Worker files").option("--out-dir <dir>", "Output directory", "cloudflare").option("--worker <name>", "Worker name", "shortlinks").option("--origin <url>", "Origin redirect server URL", process.env.SHORTLINKS_ORIGIN || "https://shortlinks.example.com").option("-j, --json", "Output JSON").action((opts) => {
+cfCmd.command("worker").description("Write Cloudflare Worker files").option("--out-dir <dir>", "Output directory", "cloudflare").option("--worker <name>", "Worker name", "shortlinks").option("--origin <url>", "Origin redirect server URL", process.env.SHORTLINKS_ORIGIN || "https://shortlinks.example.com").option("--attachments-origin <url>", "Origin URL for reserved attachment paths", process.env.ATTACHMENTS_ORIGIN).option("-j, --json", "Output JSON").action((opts) => {
   try {
-    const result = writeWorkerFiles({ outDir: opts.outDir, workerName: opts.worker, origin: opts.origin });
+    const result = writeWorkerFiles({
+      outDir: opts.outDir,
+      workerName: opts.worker,
+      origin: opts.origin,
+      attachmentsOrigin: opts.attachmentsOrigin
+    });
     print2(result, opts, () => {
       console.log(source_default.green(`Wrote ${result.workerPath}`));
       console.log(source_default.green(`Wrote ${result.wranglerPath}`));

package/dist/cloudflare.d.ts

@@ -32,6 +32,7 @@ export declare function writeWorkerFiles(options?: {
     outDir?: string;
     workerName?: string;
     origin?: string;
+    attachmentsOrigin?: string;
 }): {
     workerPath: string;
     wranglerPath: string;

package/dist/cloudflare.js

@@ -56,26 +56,33 @@ function generateWorkerScript() {
     }
 
     const incoming = new URL(request.url);
+    const proxyTo = (targetOrigin, marker) => {
+      const upstream = new URL(incoming.pathname + incoming.search, targetOrigin);
+      const headers = new Headers(request.headers);
+      headers.set("x-forwarded-host", incoming.host);
+      headers.set("x-shortlinks-worker", marker);
+
+      return fetch(upstream.toString(), {
+        method: request.method,
+        headers,
+        body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
+        redirect: "manual"
+      });
+    };
+
     const reserved = (env.SHORTLINKS_RESERVED_PATH_PREFIXES || "a")
       .split(",")
       .map((value) => value.trim().toLowerCase())
       .filter(Boolean);
     const firstSegment = decodeURIComponent(incoming.pathname.replace(/^\\/+/, "").split("/")[0] || "").toLowerCase();
     if (firstSegment && reserved.includes(firstSegment)) {
+      if (env.ATTACHMENTS_ORIGIN) {
+        return proxyTo(env.ATTACHMENTS_ORIGIN, "attachments");
+      }
       return new Response("Reserved path prefix", { status: 404 });
     }
 
-    const upstream = new URL(incoming.pathname + incoming.search, origin);
-    const headers = new Headers(request.headers);
-    headers.set("x-forwarded-host", incoming.host);
-    headers.set("x-shortlinks-worker", "cloudflare");
-
-    return fetch(upstream.toString(), {
-      method: request.method,
-      headers,
-      body: request.method === "GET" || request.method === "HEAD" ? undefined : request.body,
-      redirect: "manual"
-    });
+    return proxyTo(origin, "cloudflare");
   }
 };
 `;
@@ -93,6 +100,7 @@ compatibility_date = "2026-05-01"
 
 [vars]
 SHORTLINKS_ORIGIN = "${options.origin || "https://shortlinks.example.com"}"
+ATTACHMENTS_ORIGIN = "${options.attachmentsOrigin || ""}"
 SHORTLINKS_RESERVED_PATH_PREFIXES = "a"
 `);
   return { workerPath, wranglerPath };