@hasna/shortlinks 0.1.23 → 0.2.0

package/dist/serve/openapi.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OpenAPI 3 description of the shortlinks serve HTTP API.
+ *
+ * This is the single source of truth for the generated SDK
+ * (`@hasna/shortlinks-sdk`) — run `bun run sdk:generate` after changing it —
+ * and is also served live at `GET /openapi.json`.
+ */
+export declare function buildOpenApiDocument(version: string): Record<string, unknown>;

package/dist/server.js

@@ -1,4 +1,37 @@
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __require = import.meta.require;
+
 // src/store.ts
 import { createHash } from "crypto";
 

package/dist/store-interface.d.ts

@@ -0,0 +1,37 @@
+import type { AddDomainInput, Click, ClickInput, CreateLinkInput, Domain, Link, LinkStats } from "./types.js";
+export interface ListLinksOptions {
+    domain?: string;
+    activeOnly?: boolean;
+    limit?: number;
+}
+export interface TotalStats {
+    domains: number;
+    links: number;
+    clicks: number;
+}
+/**
+ * The single storage surface shared by LocalStore and ApiStore. All methods are
+ * async so one call site works against either transport with no mode branching.
+ */
+export interface Store {
+    /** Which transport backs this store (for banners/diagnostics only). */
+    readonly kind: "local" | "cloud-http";
+    addDomain(input: AddDomainInput): Promise<Domain>;
+    listDomains(): Promise<Domain[]>;
+    getDomain(hostnameOrId: string): Promise<Domain | null>;
+    getDefaultDomain(): Promise<Domain | null>;
+    createLink(input: CreateLinkInput): Promise<Link>;
+    listLinks(options?: ListLinksOptions): Promise<Link[]>;
+    getLink(domainOrSlug: string, maybeSlug?: string): Promise<Link | null>;
+    resolve(hostname: string, slug: string): Promise<Link | null>;
+    setLinkActive(domainOrSlug: string, slugOrActive: string | boolean, active?: boolean): Promise<Link>;
+    deleteLink(domainOrSlug: string, maybeSlug?: string): Promise<Link>;
+    /**
+     * Record a click. Only the on-box redirect server does this against a LocalStore;
+     * the cloud API records clicks server-side, so ApiStore rejects this call.
+     */
+    recordClick(link: Link, input?: ClickInput): Promise<Click>;
+    getStats(domainOrSlug: string, maybeSlug?: string): Promise<LinkStats>;
+    totalStats(): Promise<TotalStats>;
+    close(): Promise<void>;
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@hasna/shortlinks",
-  "version": "0.1.23",
-  "description": "CLI-only shortlink manager for custom domains, click tracking, Cloudflare setup, and app-owned Postgres runtime support",
+  "version": "0.2.0",
+  "description": "Shortlink manager for custom domains and click tracking, with local SQLite or self-hosted cloud (/v1 API + bearer key) storage and Cloudflare setup helpers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "shortlinks": "dist/cli/index.js"
+    "shortlinks": "dist/cli/index.js",
+    "shortlinks-mcp": "dist/mcp/index.js",
+    "shortlinks-serve": "dist/serve/index.js"
   },
   "exports": {
     ".": {
@@ -25,9 +27,9 @@
       "types": "./dist/pg-store.d.ts",
       "import": "./dist/pg-store.js"
     },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "import": "./dist/runtime.js"
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
     }
   },
   "files": [
@@ -39,11 +41,15 @@
     "SECURITY.md"
   ],
   "scripts": {
-    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts --outdir dist --target bun && bun build src/server.ts --outdir dist --target bun && bun build src/cloudflare.ts --outdir dist --target bun && bun build src/runtime.ts --outdir dist --target bun && bun build src/pg-store.ts --outdir dist --target bun && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build": "rm -rf dist && bun build src/cli/index.ts src/mcp/index.ts src/serve/index.ts src/sdk/index.ts src/index.ts src/server.ts src/cloudflare.ts src/pg-store.ts --root src --outdir dist --target bun --external @modelcontextprotocol/sdk --external @hasna/mcp-harness --external @hasna/mcp-harness/node && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "sdk:generate": "bun run scripts/generate-sdk.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "dev:cli": "bun run src/cli/index.ts",
-    "prepublishOnly": "bun run typecheck && bun run test && bun run build"
+    "dev:mcp": "bun run src/mcp/index.ts",
+    "dev:serve": "bun run src/serve/index.ts",
+    "verify:release": "bun run typecheck && bun run test && bun run build",
+    "prepublishOnly": "bun run verify:release"
   },
   "keywords": [
     "shortlinks",
@@ -75,11 +81,15 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@hasna/events": "^0.1.6",
+    "@hasna/mcp-harness": "file:../open-mcp",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
+    "hono": "^4.12.7",
     "pg": "^8.13.3"
   },
   "devDependencies": {
+    "@hasna/contracts": "file:../open-contracts",
     "@types/pg": "^8.11.11",
     "@types/bun": "^1.2.4",
     "typescript": "^5.7.3"

package/dist/pg-migrations.d.ts

@@ -1 +0,0 @@
-export declare const PG_MIGRATIONS: string[];

package/dist/runtime.d.ts

@@ -1,65 +0,0 @@
-export type ShortlinksStoreMode = "local" | "postgres";
-export type ShortlinksRuntimeEnv = Record<string, string | undefined>;
-export interface ShortlinksPostgresConfig {
-    provider: "postgres";
-    url: string;
-    ssl: boolean;
-}
-export interface ShortlinksRuntimeConfig {
-    service: "shortlinks";
-    mode: ShortlinksStoreMode;
-    database?: ShortlinksPostgresConfig;
-}
-export declare const SHORTLINKS_RUNTIME_ENV: {
-    readonly store: "HASNA_SHORTLINKS_STORE";
-    readonly databaseUrl: "HASNA_SHORTLINKS_DATABASE_URL";
-    readonly databaseSsl: "HASNA_SHORTLINKS_DATABASE_SSL";
-};
-export declare const SHORTLINKS_RUNTIME_FALLBACK_ENV: {
-    readonly store: "SHORTLINKS_STORE";
-    readonly databaseUrl: "SHORTLINKS_DATABASE_URL";
-    readonly databaseSsl: "SHORTLINKS_DATABASE_SSL";
-};
-export declare const CANONICAL_SHORTLINKS_POSTGRES_CLUSTER = "hasna-xyz-infra-apps-prod-postgres";
-export declare const CANONICAL_SHORTLINKS_POSTGRES_DATABASE = "shortlinks";
-export declare const CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH = "hasna/xyz/opensource/shortlinks/prod/postgres";
-export interface CanonicalShortlinksPostgresConfig {
-    cluster: typeof CANONICAL_SHORTLINKS_POSTGRES_CLUSTER;
-    database: typeof CANONICAL_SHORTLINKS_POSTGRES_DATABASE;
-    runtimeSecretPath: typeof CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH;
-    primaryEnv: typeof SHORTLINKS_RUNTIME_ENV.databaseUrl;
-    fallbackEnv: typeof SHORTLINKS_RUNTIME_FALLBACK_ENV.databaseUrl;
-}
-export interface RuntimeEnvStatus {
-    name: string;
-    active_name: string;
-    configured: boolean;
-}
-export interface ShortlinksRuntimeStatus {
-    ok: boolean;
-    service: "shortlinks";
-    mode: ShortlinksStoreMode;
-    local_default: boolean;
-    postgres_enabled: boolean;
-    database: {
-        configured: boolean;
-        provider: "postgres" | null;
-        redacted_url: string | null;
-        ssl: boolean | null;
-    };
-    env: Record<keyof typeof SHORTLINKS_RUNTIME_ENV, RuntimeEnvStatus>;
-    canonical: CanonicalShortlinksPostgresConfig;
-    issues: string[];
-    warnings: string[];
-    no_network: true;
-}
-export declare function getCanonicalShortlinksPostgresConfig(): CanonicalShortlinksPostgresConfig;
-export declare function parseShortlinksStoreMode(value: string | undefined): ShortlinksStoreMode;
-export declare function getShortlinksStoreMode(env?: ShortlinksRuntimeEnv): ShortlinksStoreMode;
-export declare function getShortlinksDatabaseUrl(env?: ShortlinksRuntimeEnv): string | undefined;
-export declare function getShortlinksDatabaseSsl(env?: ShortlinksRuntimeEnv): boolean;
-export declare function getShortlinksRuntimeEnvName(env: ShortlinksRuntimeEnv, key: keyof typeof SHORTLINKS_RUNTIME_ENV): string;
-export declare function loadShortlinksRuntimeConfig(env?: ShortlinksRuntimeEnv): ShortlinksRuntimeConfig;
-export declare function assertShortlinksPostgresConfig(config: ShortlinksRuntimeConfig): void;
-export declare function getShortlinksRuntimeStatus(env?: ShortlinksRuntimeEnv): ShortlinksRuntimeStatus;
-export declare function redactDatabaseUrl(value: string | undefined): string | null;

package/dist/runtime.js

@@ -1,181 +0,0 @@
-// @bun
-// src/runtime.ts
-var SHORTLINKS_RUNTIME_ENV = {
-  store: "HASNA_SHORTLINKS_STORE",
-  databaseUrl: "HASNA_SHORTLINKS_DATABASE_URL",
-  databaseSsl: "HASNA_SHORTLINKS_DATABASE_SSL"
-};
-var SHORTLINKS_RUNTIME_FALLBACK_ENV = {
-  store: "SHORTLINKS_STORE",
-  databaseUrl: "SHORTLINKS_DATABASE_URL",
-  databaseSsl: "SHORTLINKS_DATABASE_SSL"
-};
-var CANONICAL_SHORTLINKS_POSTGRES_CLUSTER = "hasna-xyz-infra-apps-prod-postgres";
-var CANONICAL_SHORTLINKS_POSTGRES_DATABASE = "shortlinks";
-var CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH = "hasna/xyz/opensource/shortlinks/prod/postgres";
-function getCanonicalShortlinksPostgresConfig() {
-  return {
-    cluster: CANONICAL_SHORTLINKS_POSTGRES_CLUSTER,
-    database: CANONICAL_SHORTLINKS_POSTGRES_DATABASE,
-    runtimeSecretPath: CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH,
-    primaryEnv: SHORTLINKS_RUNTIME_ENV.databaseUrl,
-    fallbackEnv: SHORTLINKS_RUNTIME_FALLBACK_ENV.databaseUrl
-  };
-}
-function parseShortlinksStoreMode(value) {
-  const normalized = clean(value)?.toLowerCase();
-  if (!normalized)
-    return "local";
-  if (normalized === "local" || normalized === "postgres")
-    return normalized;
-  if (normalized === "pg")
-    return "postgres";
-  throw new Error(`${SHORTLINKS_RUNTIME_ENV.store} must be local or postgres`);
-}
-function getShortlinksStoreMode(env = process.env) {
-  return parseShortlinksStoreMode(readRuntimeEnv(env, "store").value);
-}
-function getShortlinksDatabaseUrl(env = process.env) {
-  return readRuntimeEnv(env, "databaseUrl").value;
-}
-function getShortlinksDatabaseSsl(env = process.env) {
-  return parseBoolean(readRuntimeEnv(env, "databaseSsl").value, true);
-}
-function getShortlinksRuntimeEnvName(env, key) {
-  const primary = SHORTLINKS_RUNTIME_ENV[key];
-  if (clean(env[primary]))
-    return primary;
-  return SHORTLINKS_RUNTIME_FALLBACK_ENV[key];
-}
-function loadShortlinksRuntimeConfig(env = process.env) {
-  const mode = getShortlinksStoreMode(env);
-  const databaseUrl = getShortlinksDatabaseUrl(env);
-  return {
-    service: "shortlinks",
-    mode,
-    ...databaseUrl ? {
-      database: {
-        provider: "postgres",
-        url: databaseUrl,
-        ssl: getShortlinksDatabaseSsl(env)
-      }
-    } : {}
-  };
-}
-function assertShortlinksPostgresConfig(config) {
-  if (config.mode !== "postgres")
-    return;
-  if (!config.database?.url) {
-    throw new Error(`${SHORTLINKS_RUNTIME_ENV.databaseUrl} is required when ${SHORTLINKS_RUNTIME_ENV.store}=postgres`);
-  }
-}
-function getShortlinksRuntimeStatus(env = process.env) {
-  const issues = [];
-  const warnings = [];
-  let config;
-  try {
-    config = loadShortlinksRuntimeConfig(env);
-  } catch (error) {
-    issues.push(error instanceof Error ? error.message : String(error));
-    config = { service: "shortlinks", mode: "local" };
-  }
-  try {
-    assertShortlinksPostgresConfig(config);
-  } catch (error) {
-    issues.push(error instanceof Error ? error.message : String(error));
-  }
-  if (config.mode === "local" && config.database?.url) {
-    warnings.push(`${SHORTLINKS_RUNTIME_ENV.store}=local ignores configured Postgres database settings`);
-  }
-  return {
-    ok: issues.length === 0,
-    service: "shortlinks",
-    mode: config.mode,
-    local_default: config.mode === "local",
-    postgres_enabled: config.mode === "postgres",
-    database: {
-      configured: Boolean(config.database?.url),
-      provider: config.database?.provider ?? null,
-      redacted_url: redactDatabaseUrl(config.database?.url),
-      ssl: config.database?.ssl ?? null
-    },
-    env: runtimeEnvStatus(env),
-    canonical: getCanonicalShortlinksPostgresConfig(),
-    issues,
-    warnings,
-    no_network: true
-  };
-}
-function redactDatabaseUrl(value) {
-  if (!value)
-    return null;
-  try {
-    const url = new URL(value);
-    if (url.username)
-      url.username = "***";
-    if (url.password)
-      url.password = "***";
-    for (const key of Array.from(url.searchParams.keys())) {
-      if (isSensitiveQueryKey(key))
-        url.searchParams.set(key, "***");
-    }
-    return url.toString();
-  } catch {
-    return "(redacted)";
-  }
-}
-function runtimeEnvStatus(env) {
-  return Object.fromEntries(Object.entries(SHORTLINKS_RUNTIME_ENV).map(([key, name]) => {
-    const activeName = getShortlinksRuntimeEnvName(env, key);
-    return [
-      key,
-      {
-        name,
-        active_name: activeName,
-        configured: Boolean(clean(env[activeName]))
-      }
-    ];
-  }));
-}
-function readRuntimeEnv(env, key) {
-  const primary = SHORTLINKS_RUNTIME_ENV[key];
-  const primaryValue = clean(env[primary]);
-  if (primaryValue)
-    return { name: primary, value: primaryValue };
-  const fallback = SHORTLINKS_RUNTIME_FALLBACK_ENV[key];
-  return { name: fallback, value: clean(env[fallback]) };
-}
-function parseBoolean(value, fallback) {
-  const normalized = clean(value)?.toLowerCase();
-  if (!normalized)
-    return fallback;
-  if (["1", "true", "yes", "on"].includes(normalized))
-    return true;
-  if (["0", "false", "no", "off"].includes(normalized))
-    return false;
-  throw new Error(`${SHORTLINKS_RUNTIME_ENV.databaseSsl} must be true or false`);
-}
-function isSensitiveQueryKey(key) {
-  return /(?:^|[_-])(pass(?:word)?|pwd|secret|token|credential|auth|api[_-]?key|access[_-]?key)(?:$|[_-])/i.test(key);
-}
-function clean(value) {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : undefined;
-}
-export {
-  redactDatabaseUrl,
-  parseShortlinksStoreMode,
-  loadShortlinksRuntimeConfig,
-  getShortlinksStoreMode,
-  getShortlinksRuntimeStatus,
-  getShortlinksRuntimeEnvName,
-  getShortlinksDatabaseUrl,
-  getShortlinksDatabaseSsl,
-  getCanonicalShortlinksPostgresConfig,
-  assertShortlinksPostgresConfig,
-  SHORTLINKS_RUNTIME_FALLBACK_ENV,
-  SHORTLINKS_RUNTIME_ENV,
-  CANONICAL_SHORTLINKS_RUNTIME_SECRET_PATH,
-  CANONICAL_SHORTLINKS_POSTGRES_DATABASE,
-  CANONICAL_SHORTLINKS_POSTGRES_CLUSTER
-};