@hasna/shortlinks 0.1.15 → 0.1.17

package/dist/cli/index.js

@@ -2287,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;
   `
   ];
 });
@@ -7399,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;
   `
   ];
 });
@@ -8892,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)
   };
@@ -8922,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;
@@ -8997,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")) {
@@ -9015,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";
@@ -9201,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),
@@ -9229,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,
@@ -9316,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")) {
@@ -9334,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";
@@ -9556,6 +9613,7 @@ class ShortlinksApiClient {
         slug: input.slug,
         title: input.title,
         expires_at: input.expiresAt,
+        max_uses: input.maxUses,
         length: input.slugLength
       })
     });
@@ -9701,6 +9759,7 @@ async function handleApi(request, apiPath, store, options) {
         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);
     }
@@ -9815,7 +9874,20 @@ 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);
+    }
+    if (request.method.toUpperCase() === "HEAD") {
+      return new Response(null, {
+        status: redirectStatus,
+        headers: { location: link.destination_url }
+      });
+    }
+    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"),
@@ -10140,6 +10212,15 @@ function commandExists(command) {
   const result = spawnSync3("which", [command], { encoding: "utf-8" });
   return result.status === 0;
 }
+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 {
@@ -10343,6 +10424,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)));
@@ -10350,8 +10432,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({

package/dist/index.js

@@ -5257,6 +5257,10 @@ var SQLITE_MIGRATIONS = [
   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;
   `
 ];
 
@@ -5365,6 +5369,8 @@ function linkFromRow(row) {
   return {
     ...row,
     active: Boolean(row.active),
+    max_uses: row.max_uses ?? null,
+    used_count: row.used_count ?? 0,
     metadata: parseJsonObject(row.metadata),
     short_url: formatShortUrl(row.hostname, row.slug, publicBaseUrl)
   };
@@ -5395,6 +5401,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;
@@ -5470,15 +5483,16 @@ class ShortlinksStore {
     const timestamp = now();
     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")) {
@@ -5488,6 +5502,19 @@ class ShortlinksStore {
     }
     return this.getLink(domain.hostname, slug);
   }
+  consumeLinkUse(link) {
+    const timestamp = now();
+    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";
@@ -5671,6 +5698,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),
@@ -5699,6 +5728,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,
@@ -5786,15 +5822,16 @@ class PgShortlinksStore {
     const timestamp = now();
     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")) {
@@ -5804,6 +5841,22 @@ class PgShortlinksStore {
     }
     return await this.getLink(domain.hostname, slug);
   }
+  async consumeLinkUse(link) {
+    const timestamp = now();
+    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";
@@ -6024,6 +6077,10 @@ var PG_MIGRATIONS = [
   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;
   `
 ];
 
@@ -6283,6 +6340,7 @@ async function handleApi(request, apiPath, store, options) {
         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);
     }
@@ -6397,7 +6455,20 @@ 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);
+    }
+    if (request.method.toUpperCase() === "HEAD") {
+      return new Response(null, {
+        status: redirectStatus,
+        headers: { location: link.destination_url }
+      });
+    }
+    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"),
@@ -6484,6 +6555,7 @@ class ShortlinksApiClient {
         slug: input.slug,
         title: input.title,
         expires_at: input.expiresAt,
+        max_uses: input.maxUses,
         length: input.slugLength
       })
     });

package/dist/pg-store.d.ts

@@ -17,6 +17,7 @@ export declare class PgShortlinksStore {
     getDomain(hostnameOrId: string): Promise<Domain | null>;
     getDefaultDomain(): Promise<Domain | null>;
     createLink(input: CreateLinkInput): Promise<Link>;
+    consumeLinkUse(link: Link): Promise<Link | null>;
     listLinks(options?: {
         domain?: string;
         activeOnly?: boolean;

package/dist/server.d.ts

@@ -11,6 +11,7 @@ export interface ShortlinksRuntimeStore {
     }>;
     resolve(hostname: string, slug: string): Link | null | Promise<Link | null>;
     recordClick(link: Link, input?: ClickInput): unknown | Promise<unknown>;
+    consumeLinkUse?(link: Link): Link | null | Promise<Link | null>;
     createLink?(input: CreateLinkInput): Link | Promise<Link>;
     listLinks?(input?: {
         domain?: string;

package/dist/server.js

@@ -161,6 +161,10 @@ var SQLITE_MIGRATIONS = [
   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;
   `
 ];
 
@@ -267,6 +271,8 @@ function linkFromRow(row) {
   return {
     ...row,
     active: Boolean(row.active),
+    max_uses: row.max_uses ?? null,
+    used_count: row.used_count ?? 0,
     metadata: parseJsonObject(row.metadata),
     short_url: formatShortUrl(row.hostname, row.slug, publicBaseUrl)
   };
@@ -297,6 +303,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;
@@ -372,15 +385,16 @@ class ShortlinksStore {
     const timestamp = now();
     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")) {
@@ -390,6 +404,19 @@ class ShortlinksStore {
     }
     return this.getLink(domain.hostname, slug);
   }
+  consumeLinkUse(link) {
+    const timestamp = now();
+    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";
@@ -600,6 +627,7 @@ async function handleApi(request, apiPath, store, options) {
         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);
     }
@@ -714,7 +742,20 @@ 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);
+    }
+    if (request.method.toUpperCase() === "HEAD") {
+      return new Response(null, {
+        status: redirectStatus,
+        headers: { location: link.destination_url }
+      });
+    }
+    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"),

package/dist/storage.js

@@ -5260,6 +5260,10 @@ var SQLITE_MIGRATIONS = [
   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;
   `
 ];
 
@@ -5365,6 +5369,10 @@ var PG_MIGRATIONS = [
   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;
   `
 ];
 

package/dist/store.d.ts

@@ -9,6 +9,7 @@ export declare class ShortlinksStore {
     getDomain(hostnameOrId: string): Domain | null;
     getDefaultDomain(): Domain | null;
     createLink(input: CreateLinkInput): Link;
+    consumeLinkUse(link: Link): Link | null;
     listLinks(options?: {
         domain?: string;
         activeOnly?: boolean;

package/dist/types.d.ts

@@ -23,6 +23,8 @@ export interface Link {
     title: string | null;
     active: boolean;
     expires_at: string | null;
+    max_uses: number | null;
+    used_count: number;
     metadata: Record<string, unknown>;
     machine_id: string | null;
     synced_at: string | null;
@@ -66,6 +68,7 @@ export interface CreateLinkInput {
     slug?: string;
     title?: string;
     expiresAt?: string;
+    maxUses?: number | null;
     metadata?: Record<string, unknown>;
     slugLength?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/shortlinks",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "CLI-only shortlink manager for custom domains, click tracking, Cloudflare setup, and repo-native storage sync",
   "type": "module",
   "main": "dist/index.js",