@hasna/shortlinks 0.1.14 → 0.1.16

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)
@@ -2273,6 +2287,10 @@ var init_database = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_clicks_domain ON clicks(domain_id);
   CREATE INDEX IF NOT EXISTS idx_clicks_clicked_at ON clicks(clicked_at);
   CREATE INDEX IF NOT EXISTS idx_clicks_updated ON clicks(updated_at);
+  `,
+    `
+  ALTER TABLE links ADD COLUMN max_uses INTEGER;
+  ALTER TABLE links ADD COLUMN used_count INTEGER NOT NULL DEFAULT 0;
   `
   ];
 });
@@ -7385,6 +7403,10 @@ var init_pg_migrations = __esm(() => {
   CREATE INDEX IF NOT EXISTS idx_clicks_domain ON clicks(domain_id);
   CREATE INDEX IF NOT EXISTS idx_clicks_clicked_at ON clicks(clicked_at);
   CREATE INDEX IF NOT EXISTS idx_clicks_updated ON clicks(updated_at);
+  `,
+    `
+  ALTER TABLE links ADD COLUMN IF NOT EXISTS max_uses INTEGER;
+  ALTER TABLE links ADD COLUMN IF NOT EXISTS used_count INTEGER NOT NULL DEFAULT 0;
   `
   ];
 });
@@ -8878,6 +8900,8 @@ function linkFromRow(row) {
   return {
     ...row,
     active: Boolean(row.active),
+    max_uses: row.max_uses ?? null,
+    used_count: row.used_count ?? 0,
     metadata: parseJsonObject2(row.metadata),
     short_url: formatShortUrl(row.hostname, row.slug, publicBaseUrl)
   };
@@ -8908,6 +8932,13 @@ function isoOrNull(input) {
     throw new Error(`Invalid date: ${input}`);
   return date.toISOString();
 }
+function normalizeMaxUses(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (!Number.isInteger(value) || value <= 0)
+    throw new Error("maxUses must be a positive integer.");
+  return value;
+}
 
 class ShortlinksStore {
   database;
@@ -8983,15 +9014,16 @@ class ShortlinksStore {
     const timestamp = now2();
     const machineId = getMachineId();
     const expiresAt = isoOrNull(input.expiresAt);
+    const maxUses = normalizeMaxUses(input.maxUses);
     const slug = input.slug ? normalizeSlug(input.slug) : this.generateAvailableSlug(domain.id, input.slugLength || DEFAULT_SLUG_LENGTH);
     try {
       this.database.db.query(`
         INSERT INTO links (
-          id, domain_id, slug, destination_url, title, active, expires_at, metadata,
+          id, domain_id, slug, destination_url, title, active, expires_at, max_uses, used_count, metadata,
           machine_id, synced_at, created_at, updated_at
         )
-        VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, NULL, ?, ?)
-      `).run(makeId("lnk"), domain.id, slug, destinationUrl, input.title || null, expiresAt, JSON.stringify(input.metadata || {}), machineId, timestamp, timestamp);
+        VALUES (?, ?, ?, ?, ?, 1, ?, ?, 0, ?, ?, NULL, ?, ?)
+      `).run(makeId("lnk"), domain.id, slug, destinationUrl, input.title || null, expiresAt, maxUses, JSON.stringify(input.metadata || {}), machineId, timestamp, timestamp);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes("UNIQUE")) {
@@ -9001,6 +9033,19 @@ class ShortlinksStore {
     }
     return this.getLink(domain.hostname, slug);
   }
+  consumeLinkUse(link) {
+    const timestamp = now2();
+    const result = this.database.db.query(`
+      UPDATE links
+      SET used_count = used_count + 1, updated_at = ?, synced_at = NULL
+      WHERE id = ?
+        AND active = 1
+        AND (max_uses IS NULL OR used_count < max_uses)
+    `).run(timestamp, link.id);
+    if (result.changes === 0)
+      return null;
+    return this.getLink(link.hostname, link.slug);
+  }
   listLinks(options = {}) {
     const params = [];
     let where = "WHERE 1 = 1";
@@ -9187,6 +9232,8 @@ function linkFromRow2(row) {
   return {
     ...row,
     active: Boolean(row.active),
+    max_uses: row.max_uses ?? null,
+    used_count: row.used_count ?? 0,
     expires_at: nullableIso(row.expires_at),
     synced_at: nullableIso(row.synced_at),
     created_at: toIsoString(row.created_at),
@@ -9215,6 +9262,13 @@ function isoOrNull2(input) {
     throw new Error(`Invalid date: ${input}`);
   return date.toISOString();
 }
+function normalizeMaxUses2(value) {
+  if (value === null || value === undefined)
+    return null;
+  if (!Number.isInteger(value) || value <= 0)
+    throw new Error("maxUses must be a positive integer.");
+  return value;
+}
 function clickFromRow2(row) {
   return {
     ...row,
@@ -9302,15 +9356,16 @@ class PgShortlinksStore {
     const timestamp = now2();
     const machineId = getMachineId();
     const expiresAt = isoOrNull2(input.expiresAt);
+    const maxUses = normalizeMaxUses2(input.maxUses);
     const slug = input.slug ? normalizeSlug(input.slug) : await this.generateAvailableSlug(domain.id, input.slugLength || DEFAULT_SLUG_LENGTH);
     try {
       await this.pg.run(`
         INSERT INTO links (
-          id, domain_id, slug, destination_url, title, active, expires_at, metadata,
+          id, domain_id, slug, destination_url, title, active, expires_at, max_uses, used_count, metadata,
           machine_id, synced_at, created_at, updated_at
         )
-        VALUES (?, ?, ?, ?, ?, 1, ?, ?, ?, NULL, ?, ?)
-      `, makeId("lnk"), domain.id, slug, destinationUrl, input.title || null, expiresAt, JSON.stringify(input.metadata || {}), machineId, timestamp, timestamp);
+        VALUES (?, ?, ?, ?, ?, 1, ?, ?, 0, ?, ?, NULL, ?, ?)
+      `, makeId("lnk"), domain.id, slug, destinationUrl, input.title || null, expiresAt, maxUses, JSON.stringify(input.metadata || {}), machineId, timestamp, timestamp);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       if (message.includes("unique") || message.includes("duplicate")) {
@@ -9320,6 +9375,22 @@ class PgShortlinksStore {
     }
     return await this.getLink(domain.hostname, slug);
   }
+  async consumeLinkUse(link) {
+    const timestamp = now2();
+    await this.pg.run(`
+      UPDATE links
+      SET used_count = used_count + 1, updated_at = ?, synced_at = NULL
+      WHERE id = ?
+        AND active = 1
+        AND (max_uses IS NULL OR used_count < max_uses)
+    `, timestamp, link.id);
+    const refreshed = await this.getLink(link.hostname, link.slug);
+    if (!refreshed)
+      return null;
+    if (link.max_uses !== null && refreshed.used_count === link.used_count)
+      return null;
+    return refreshed;
+  }
   async listLinks(options = {}) {
     const params = [];
     let where = "WHERE 1 = 1";
@@ -9473,6 +9544,157 @@ 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,
+        max_uses: input.maxUses,
+        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 +9702,121 @@ 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,
+        maxUses: typeof body.max_uses === "number" ? body.max_uses : typeof body.maxUses === "number" ? body.maxUses : 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 +9835,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() });
     }
@@ -9532,7 +9874,14 @@ function createShortlinksHandler(options = {}) {
       return json({ error: "Shortlink is disabled.", slug, host }, 410);
     if (isExpired(link))
       return json({ error: "Shortlink is expired.", slug, host }, 410);
-    await store.recordClick(link, {
+    if (link.max_uses !== null && link.used_count >= link.max_uses) {
+      return json({ error: "Shortlink max uses reached.", slug, host }, 410);
+    }
+    const consumed = store.consumeLinkUse ? await store.consumeLinkUse(link) : link;
+    if (!consumed) {
+      return json({ error: "Shortlink max uses reached.", slug, host }, 410);
+    }
+    await store.recordClick(consumed, {
       ip: getClientIp(request),
       userAgent: request.headers.get("user-agent"),
       referer: request.headers.get("referer"),
@@ -9635,9 +9984,9 @@ 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) {
@@ -9823,13 +10172,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);
@@ -9851,7 +10206,16 @@ 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");
+function parseMaxUses(opts) {
+  const raw = opts.maxUses ?? opts.maxClicks;
+  if (!raw)
+    return;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0)
+    throw new Error("--max-uses must be a positive integer");
+  return parsed;
+}
+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) => {
@@ -9891,19 +10255,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;
@@ -9916,7 +10303,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);
   }
@@ -10027,6 +10418,7 @@ async function createLinkAction(url, opts) {
       slug: opts.slug,
       title: opts.title,
       expiresAt: opts.expires,
+      maxUses: parseMaxUses(opts),
       slugLength: opts.length ? Number(opts.length) : undefined
     }));
     print2(link, opts, () => console.log(formatLink(link)));
@@ -10034,8 +10426,8 @@ async function createLinkAction(url, opts) {
     handleError(error);
   }
 }
-linkCmd.command("create <url>").description("Create a shortlink").option("--domain <hostname>", "Domain to use").option("--slug <slug>", "Custom slug").option("--title <title>", "Human title").option("--expires <date>", "Expiration date").option("--length <n>", "Generated slug length", "7").option("-j, --json", "Output JSON").action(createLinkAction);
-program2.command("create <url>").description("Create a shortlink").option("--domain <hostname>", "Domain to use").option("--slug <slug>", "Custom slug").option("--title <title>", "Human title").option("--expires <date>", "Expiration date").option("--length <n>", "Generated slug length", "7").option("-j, --json", "Output JSON").action(createLinkAction);
+linkCmd.command("create <url>").description("Create a shortlink").option("--domain <hostname>", "Domain to use").option("--slug <slug>", "Custom slug").option("--title <title>", "Human title").option("--expires <date>", "Expiration date").option("--max-uses <count>", "Maximum successful redirects").option("--max-clicks <count>", "Alias for --max-uses").option("--length <n>", "Generated slug length", "7").option("-j, --json", "Output JSON").action(createLinkAction);
+program2.command("create <url>").description("Create a shortlink").option("--domain <hostname>", "Domain to use").option("--slug <slug>", "Custom slug").option("--title <title>", "Human title").option("--expires <date>", "Expiration date").option("--max-uses <count>", "Maximum successful redirects").option("--max-clicks <count>", "Alias for --max-uses").option("--length <n>", "Generated slug length", "7").option("-j, --json", "Output JSON").action(createLinkAction);
 linkCmd.command("list").description("List shortlinks").option("--domain <hostname>", "Filter by domain").option("--active", "Only active links").option("--limit <n>", "Maximum rows", "100").option("-j, --json", "Output JSON").action(async (opts) => {
   try {
     const links = await withRuntimeStore((store) => store.listLinks({
@@ -10111,7 +10503,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({
@@ -10119,7 +10511,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})`));