@ai-matrx/kit 0.5.1 → 0.6.0

package/dist/short-link.cjs

@@ -0,0 +1,97 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/short-link.ts
+var short_link_exports = {};
+__export(short_link_exports, {
+  SHORT_LINK_PATH_PREFIX: () => SHORT_LINK_PATH_PREFIX,
+  SHORT_LINK_TOKEN_ALPHABET: () => SHORT_LINK_TOKEN_ALPHABET,
+  SHORT_LINK_TOKEN_LENGTH: () => SHORT_LINK_TOKEN_LENGTH,
+  isShortLinkToken: () => isShortLinkToken,
+  mintShortLink: () => mintShortLink,
+  normalizeShortLinkToken: () => normalizeShortLinkToken,
+  resolveShortLinkPath: () => resolveShortLinkPath,
+  shortLinkPath: () => shortLinkPath,
+  shortLinkUrl: () => shortLinkUrl
+});
+module.exports = __toCommonJS(short_link_exports);
+var SHORT_LINK_TOKEN_ALPHABET = "23456789abcdefghijkmnpqrstuvwxyz";
+var SHORT_LINK_TOKEN_LENGTH = 10;
+var SHORT_LINK_PATH_PREFIX = "/r/";
+var TOKEN_RE = new RegExp(`^[${SHORT_LINK_TOKEN_ALPHABET}]{${SHORT_LINK_TOKEN_LENGTH}}$`);
+function normalizeShortLinkToken(candidate) {
+  const token = (candidate ?? "").trim().toLowerCase();
+  return TOKEN_RE.test(token) ? token : null;
+}
+function isShortLinkToken(candidate) {
+  return normalizeShortLinkToken(candidate) !== null;
+}
+function shortLinkPath(token) {
+  const normalized = normalizeShortLinkToken(token);
+  if (!normalized) {
+    throw new Error(
+      `shortLinkPath: ${JSON.stringify(token)} is not a short-link token (${SHORT_LINK_TOKEN_LENGTH} chars of "${SHORT_LINK_TOKEN_ALPHABET}")`
+    );
+  }
+  return `${SHORT_LINK_PATH_PREFIX}${normalized}`;
+}
+function shortLinkUrl(origin, token) {
+  return `${origin.replace(/\/+$/, "")}${shortLinkPath(token)}`;
+}
+function resolveOrigin(origin) {
+  if (origin) return origin;
+  if (typeof window !== "undefined" && window.location?.origin) {
+    return window.location.origin;
+  }
+  return null;
+}
+async function mintShortLink(client, options) {
+  if (!options.path.startsWith("/") || options.path.startsWith("//")) {
+    return { ok: false, error: "Only a same-app path (starting with a single '/') can be shortened" };
+  }
+  const origin = resolveOrigin(options.origin);
+  if (!origin) {
+    return { ok: false, error: "No origin: pass options.origin outside a browser" };
+  }
+  const { data, error } = await client.rpc("shorten_app_url", {
+    p_path: options.path,
+    p_organization_id: options.organizationId,
+    ...options.expiresAt ? { p_expires_at: options.expiresAt } : {}
+  });
+  if (error) return { ok: false, error: error.message };
+  const result = data;
+  const token = result?.ok ? normalizeShortLinkToken(result.token) : null;
+  if (!token) {
+    return { ok: false, error: result?.error ?? "The mint door returned no token" };
+  }
+  return { ok: true, token, path: shortLinkPath(token), url: shortLinkUrl(origin, token) };
+}
+async function resolveShortLinkPath(client, token) {
+  const normalized = normalizeShortLinkToken(token);
+  if (!normalized) return { ok: false };
+  const { data, error } = await client.rpc("resolve_short_link", { p_token: normalized });
+  if (error) return { ok: false };
+  const result = data;
+  const targetPath = result?.ok ? result.target_path : void 0;
+  if (!targetPath || !targetPath.startsWith("/") || targetPath.startsWith("//")) {
+    return { ok: false };
+  }
+  return { ok: true, targetPath };
+}
+//# sourceMappingURL=short-link.cjs.map

package/dist/short-link.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/short-link.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/short-link — the platform short-link CONTRACT, in one place.\n *\n * The primitive itself lives in the database (migration `0557_platform_short_links`):\n * `platform.short_links` holds `token → same-app path`, org-scoped and expiring;\n * `platform.create_short_link` mints (server-side only); `public.resolve_short_link`\n * resolves (anon-callable; answers with a PATH, never content — the target route's\n * own auth gates everything). The frontend redirect route is `/r/[token]`\n * (matrx-frontend `app/(public)/r/[token]`), and the notification spine mints per\n * SMS leg (aidream `services/notifications/short_links.py`).\n *\n * This module is the shared vocabulary every client needs to speak about those\n * tokens — alphabet, length, validation, and the URL shape — so no consumer ever\n * re-declares it. 🚨 `SHORT_LINK_TOKEN_ALPHABET` and `SHORT_LINK_TOKEN_LENGTH`\n * mirror `platform.create_short_link` EXACTLY; change one and you change both.\n *\n * 🚨 A short link is a URL, not a permission. The primitive that grants\n * anonymous access to content is `platform.share_links` (`/s/[token]`, 64-hex\n * tokens) — a different system, deliberately. Never shorten by minting a share\n * link, and never share by minting a short link.\n *\n * Pure logic — no DOM, no React, no network; safe in Server Components, route\n * handlers, workers, and Node scripts.\n */\n\n/**\n * 32 characters: digits 2–9 plus a–z minus `l` and `o`. 256 % 32 = 0, so the\n * mint maps random bytes without modulo bias; lowercase-only survives channels\n * that case-mangle (the resolver lowercases before lookup); the ambiguous\n * glyphs (`0/o`, `1/l`) never appear.\n */\nexport const SHORT_LINK_TOKEN_ALPHABET = \"23456789abcdefghijkmnpqrstuvwxyz\";\n\n/** 10 characters × 5 bits = 50 bits — unguessable at any realistic probe rate. */\nexport const SHORT_LINK_TOKEN_LENGTH = 10;\n\n/** The resolve route on the app origin (matrx-frontend `app/(public)/r/[token]`). */\nexport const SHORT_LINK_PATH_PREFIX = \"/r/\";\n\nconst TOKEN_RE = new RegExp(`^[${SHORT_LINK_TOKEN_ALPHABET}]{${SHORT_LINK_TOKEN_LENGTH}}$`);\n\n/**\n * Trim, lowercase, and shape-check a candidate token. Returns the normalized\n * token, or `null` for anything outside the contract — the resolver would\n * refuse it anyway, so callers can skip the round trip.\n */\nexport function normalizeShortLinkToken(candidate: string | null | undefined): string | null {\n  const token = (candidate ?? \"\").trim().toLowerCase();\n  return TOKEN_RE.test(token) ? token : null;\n}\n\n/** Whether a string is a well-formed short-link token (after normalization). */\nexport function isShortLinkToken(candidate: string | null | undefined): boolean {\n  return normalizeShortLinkToken(candidate) !== null;\n}\n\n/** The app-relative path a token resolves at: `/r/<token>`. */\nexport function shortLinkPath(token: string): string {\n  const normalized = normalizeShortLinkToken(token);\n  if (!normalized) {\n    throw new Error(\n      `shortLinkPath: ${JSON.stringify(token)} is not a short-link token ` +\n        `(${SHORT_LINK_TOKEN_LENGTH} chars of \"${SHORT_LINK_TOKEN_ALPHABET}\")`,\n    );\n  }\n  return `${SHORT_LINK_PATH_PREFIX}${normalized}`;\n}\n\n/**\n * The absolute short URL for a token on a given origin, e.g.\n * `shortLinkUrl(\"https://app.aimatrx.com\", token)` → `https://app.aimatrx.com/r/<token>`.\n */\nexport function shortLinkUrl(origin: string, token: string): string {\n  return `${origin.replace(/\\/+$/, \"\")}${shortLinkPath(token)}`;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The client half — the WHOLE mint/resolve logic, so a consumer adds nothing.\n//\n// Pass your Supabase client (or anything with a compatible `.rpc`) and you are\n// done: `mintShortLink(supabase, { path, organizationId })` calls the platform's\n// authenticated mint door (`public.shorten_app_url`, org-membership-gated) and\n// hands back the finished short URL; `resolveShortLinkPath(supabase, token)`\n// calls the anon resolver (`public.resolve_short_link`). No app writes its own\n// shortener logic, ever — the only thing outside this module is the shared\n// database that stores the tokens, which is exactly where shared state lives.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Anything with a Supabase-shaped `.rpc` — pass the Supabase client itself. */\nexport interface ShortLinkClient {\n  rpc(\n    fn: string,\n    args?: Record<string, unknown>,\n  ): PromiseLike<{ data: unknown; error: { message: string } | null }>;\n}\n\nexport interface MintShortLinkOptions {\n  /** Same-app path to shorten (must start with a single `/`). */\n  path: string;\n  /** The organization the link belongs to — the caller must be a member. */\n  organizationId: string;\n  /** ISO timestamp; the platform default (365 days) applies when omitted. */\n  expiresAt?: string;\n  /** Origin for the returned URL; defaults to `window.location.origin`. */\n  origin?: string;\n}\n\nexport type MintShortLinkResult =\n  | { ok: true; token: string; path: string; url: string }\n  | { ok: false; error: string };\n\nfunction resolveOrigin(origin?: string): string | null {\n  if (origin) return origin;\n  if (typeof window !== \"undefined\" && window.location?.origin) {\n    return window.location.origin;\n  }\n  return null;\n}\n\n/** Mint a short link through the platform's authenticated mint door. */\nexport async function mintShortLink(\n  client: ShortLinkClient,\n  options: MintShortLinkOptions,\n): Promise<MintShortLinkResult> {\n  if (!options.path.startsWith(\"/\") || options.path.startsWith(\"//\")) {\n    return { ok: false, error: \"Only a same-app path (starting with a single '/') can be shortened\" };\n  }\n  const origin = resolveOrigin(options.origin);\n  if (!origin) {\n    return { ok: false, error: \"No origin: pass options.origin outside a browser\" };\n  }\n  const { data, error } = await client.rpc(\"shorten_app_url\", {\n    p_path: options.path,\n    p_organization_id: options.organizationId,\n    ...(options.expiresAt ? { p_expires_at: options.expiresAt } : {}),\n  });\n  if (error) return { ok: false, error: error.message };\n  const result = data as { ok?: boolean; token?: string; error?: string } | null;\n  const token = result?.ok ? normalizeShortLinkToken(result.token) : null;\n  if (!token) {\n    return { ok: false, error: result?.error ?? \"The mint door returned no token\" };\n  }\n  return { ok: true, token, path: shortLinkPath(token), url: shortLinkUrl(origin, token) };\n}\n\nexport type ResolveShortLinkResult =\n  | { ok: true; targetPath: string }\n  | { ok: false };\n\n/**\n * Resolve a short token to its target path through the anon resolver.\n * `{ok:false}` covers invalid, unknown, and expired identically — the platform\n * deliberately does not distinguish them.\n */\nexport async function resolveShortLinkPath(\n  client: ShortLinkClient,\n  token: string,\n): Promise<ResolveShortLinkResult> {\n  const normalized = normalizeShortLinkToken(token);\n  if (!normalized) return { ok: false };\n  const { data, error } = await client.rpc(\"resolve_short_link\", { p_token: normalized });\n  if (error) return { ok: false };\n  const result = data as { ok?: boolean; target_path?: string } | null;\n  const targetPath = result?.ok ? result.target_path : undefined;\n  if (!targetPath || !targetPath.startsWith(\"/\") || targetPath.startsWith(\"//\")) {\n    return { ok: false };\n  }\n  return { ok: true, targetPath };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA+BO,IAAM,4BAA4B;AAGlC,IAAM,0BAA0B;AAGhC,IAAM,yBAAyB;AAEtC,IAAM,WAAW,IAAI,OAAO,KAAK,yBAAyB,KAAK,uBAAuB,IAAI;AAOnF,SAAS,wBAAwB,WAAqD;AAC3F,QAAM,SAAS,aAAa,IAAI,KAAK,EAAE,YAAY;AACnD,SAAO,SAAS,KAAK,KAAK,IAAI,QAAQ;AACxC;AAGO,SAAS,iBAAiB,WAA+C;AAC9E,SAAO,wBAAwB,SAAS,MAAM;AAChD;AAGO,SAAS,cAAc,OAAuB;AACnD,QAAM,aAAa,wBAAwB,KAAK;AAChD,MAAI,CAAC,YAAY;AACf,UAAM,IAAI;AAAA,MACR,kBAAkB,KAAK,UAAU,KAAK,CAAC,+BACjC,uBAAuB,cAAc,yBAAyB;AAAA,IACtE;AAAA,EACF;AACA,SAAO,GAAG,sBAAsB,GAAG,UAAU;AAC/C;AAMO,SAAS,aAAa,QAAgB,OAAuB;AAClE,SAAO,GAAG,OAAO,QAAQ,QAAQ,EAAE,CAAC,GAAG,cAAc,KAAK,CAAC;AAC7D;AAqCA,SAAS,cAAc,QAAgC;AACrD,MAAI,OAAQ,QAAO;AACnB,MAAI,OAAO,WAAW,eAAe,OAAO,UAAU,QAAQ;AAC5D,WAAO,OAAO,SAAS;AAAA,EACzB;AACA,SAAO;AACT;AAGA,eAAsB,cACpB,QACA,SAC8B;AAC9B,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG,KAAK,QAAQ,KAAK,WAAW,IAAI,GAAG;AAClE,WAAO,EAAE,IAAI,OAAO,OAAO,qEAAqE;AAAA,EAClG;AACA,QAAM,SAAS,cAAc,QAAQ,MAAM;AAC3C,MAAI,CAAC,QAAQ;AACX,WAAO,EAAE,IAAI,OAAO,OAAO,mDAAmD;AAAA,EAChF;AACA,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,mBAAmB;AAAA,IAC1D,QAAQ,QAAQ;AAAA,IAChB,mBAAmB,QAAQ;AAAA,IAC3B,GAAI,QAAQ,YAAY,EAAE,cAAc,QAAQ,UAAU,IAAI,CAAC;AAAA,EACjE,CAAC;AACD,MAAI,MAAO,QAAO,EAAE,IAAI,OAAO,OAAO,MAAM,QAAQ;AACpD,QAAM,SAAS;AACf,QAAM,QAAQ,QAAQ,KAAK,wBAAwB,OAAO,KAAK,IAAI;AACnE,MAAI,CAAC,OAAO;AACV,WAAO,EAAE,IAAI,OAAO,OAAO,QAAQ,SAAS,kCAAkC;AAAA,EAChF;AACA,SAAO,EAAE,IAAI,MAAM,OAAO,MAAM,cAAc,KAAK,GAAG,KAAK,aAAa,QAAQ,KAAK,EAAE;AACzF;AAWA,eAAsB,qBACpB,QACA,OACiC;AACjC,QAAM,aAAa,wBAAwB,KAAK;AAChD,MAAI,CAAC,WAAY,QAAO,EAAE,IAAI,MAAM;AACpC,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,sBAAsB,EAAE,SAAS,WAAW,CAAC;AACtF,MAAI,MAAO,QAAO,EAAE,IAAI,MAAM;AAC9B,QAAM,SAAS;AACf,QAAM,aAAa,QAAQ,KAAK,OAAO,cAAc;AACrD,MAAI,CAAC,cAAc,CAAC,WAAW,WAAW,GAAG,KAAK,WAAW,WAAW,IAAI,GAAG;AAC7E,WAAO,EAAE,IAAI,MAAM;AAAA,EACrB;AACA,SAAO,EAAE,IAAI,MAAM,WAAW;AAChC;","names":[]}

package/dist/short-link.d.cts

@@ -0,0 +1,94 @@
+/**
+ * @ai-matrx/kit/short-link — the platform short-link CONTRACT, in one place.
+ *
+ * The primitive itself lives in the database (migration `0557_platform_short_links`):
+ * `platform.short_links` holds `token → same-app path`, org-scoped and expiring;
+ * `platform.create_short_link` mints (server-side only); `public.resolve_short_link`
+ * resolves (anon-callable; answers with a PATH, never content — the target route's
+ * own auth gates everything). The frontend redirect route is `/r/[token]`
+ * (matrx-frontend `app/(public)/r/[token]`), and the notification spine mints per
+ * SMS leg (aidream `services/notifications/short_links.py`).
+ *
+ * This module is the shared vocabulary every client needs to speak about those
+ * tokens — alphabet, length, validation, and the URL shape — so no consumer ever
+ * re-declares it. 🚨 `SHORT_LINK_TOKEN_ALPHABET` and `SHORT_LINK_TOKEN_LENGTH`
+ * mirror `platform.create_short_link` EXACTLY; change one and you change both.
+ *
+ * 🚨 A short link is a URL, not a permission. The primitive that grants
+ * anonymous access to content is `platform.share_links` (`/s/[token]`, 64-hex
+ * tokens) — a different system, deliberately. Never shorten by minting a share
+ * link, and never share by minting a short link.
+ *
+ * Pure logic — no DOM, no React, no network; safe in Server Components, route
+ * handlers, workers, and Node scripts.
+ */
+/**
+ * 32 characters: digits 2–9 plus a–z minus `l` and `o`. 256 % 32 = 0, so the
+ * mint maps random bytes without modulo bias; lowercase-only survives channels
+ * that case-mangle (the resolver lowercases before lookup); the ambiguous
+ * glyphs (`0/o`, `1/l`) never appear.
+ */
+declare const SHORT_LINK_TOKEN_ALPHABET = "23456789abcdefghijkmnpqrstuvwxyz";
+/** 10 characters × 5 bits = 50 bits — unguessable at any realistic probe rate. */
+declare const SHORT_LINK_TOKEN_LENGTH = 10;
+/** The resolve route on the app origin (matrx-frontend `app/(public)/r/[token]`). */
+declare const SHORT_LINK_PATH_PREFIX = "/r/";
+/**
+ * Trim, lowercase, and shape-check a candidate token. Returns the normalized
+ * token, or `null` for anything outside the contract — the resolver would
+ * refuse it anyway, so callers can skip the round trip.
+ */
+declare function normalizeShortLinkToken(candidate: string | null | undefined): string | null;
+/** Whether a string is a well-formed short-link token (after normalization). */
+declare function isShortLinkToken(candidate: string | null | undefined): boolean;
+/** The app-relative path a token resolves at: `/r/<token>`. */
+declare function shortLinkPath(token: string): string;
+/**
+ * The absolute short URL for a token on a given origin, e.g.
+ * `shortLinkUrl("https://app.aimatrx.com", token)` → `https://app.aimatrx.com/r/<token>`.
+ */
+declare function shortLinkUrl(origin: string, token: string): string;
+/** Anything with a Supabase-shaped `.rpc` — pass the Supabase client itself. */
+interface ShortLinkClient {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+interface MintShortLinkOptions {
+    /** Same-app path to shorten (must start with a single `/`). */
+    path: string;
+    /** The organization the link belongs to — the caller must be a member. */
+    organizationId: string;
+    /** ISO timestamp; the platform default (365 days) applies when omitted. */
+    expiresAt?: string;
+    /** Origin for the returned URL; defaults to `window.location.origin`. */
+    origin?: string;
+}
+type MintShortLinkResult = {
+    ok: true;
+    token: string;
+    path: string;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Mint a short link through the platform's authenticated mint door. */
+declare function mintShortLink(client: ShortLinkClient, options: MintShortLinkOptions): Promise<MintShortLinkResult>;
+type ResolveShortLinkResult = {
+    ok: true;
+    targetPath: string;
+} | {
+    ok: false;
+};
+/**
+ * Resolve a short token to its target path through the anon resolver.
+ * `{ok:false}` covers invalid, unknown, and expired identically — the platform
+ * deliberately does not distinguish them.
+ */
+declare function resolveShortLinkPath(client: ShortLinkClient, token: string): Promise<ResolveShortLinkResult>;
+
+export { type MintShortLinkOptions, type MintShortLinkResult, type ResolveShortLinkResult, SHORT_LINK_PATH_PREFIX, SHORT_LINK_TOKEN_ALPHABET, SHORT_LINK_TOKEN_LENGTH, type ShortLinkClient, isShortLinkToken, mintShortLink, normalizeShortLinkToken, resolveShortLinkPath, shortLinkPath, shortLinkUrl };

package/dist/short-link.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @ai-matrx/kit/short-link — the platform short-link CONTRACT, in one place.
+ *
+ * The primitive itself lives in the database (migration `0557_platform_short_links`):
+ * `platform.short_links` holds `token → same-app path`, org-scoped and expiring;
+ * `platform.create_short_link` mints (server-side only); `public.resolve_short_link`
+ * resolves (anon-callable; answers with a PATH, never content — the target route's
+ * own auth gates everything). The frontend redirect route is `/r/[token]`
+ * (matrx-frontend `app/(public)/r/[token]`), and the notification spine mints per
+ * SMS leg (aidream `services/notifications/short_links.py`).
+ *
+ * This module is the shared vocabulary every client needs to speak about those
+ * tokens — alphabet, length, validation, and the URL shape — so no consumer ever
+ * re-declares it. 🚨 `SHORT_LINK_TOKEN_ALPHABET` and `SHORT_LINK_TOKEN_LENGTH`
+ * mirror `platform.create_short_link` EXACTLY; change one and you change both.
+ *
+ * 🚨 A short link is a URL, not a permission. The primitive that grants
+ * anonymous access to content is `platform.share_links` (`/s/[token]`, 64-hex
+ * tokens) — a different system, deliberately. Never shorten by minting a share
+ * link, and never share by minting a short link.
+ *
+ * Pure logic — no DOM, no React, no network; safe in Server Components, route
+ * handlers, workers, and Node scripts.
+ */
+/**
+ * 32 characters: digits 2–9 plus a–z minus `l` and `o`. 256 % 32 = 0, so the
+ * mint maps random bytes without modulo bias; lowercase-only survives channels
+ * that case-mangle (the resolver lowercases before lookup); the ambiguous
+ * glyphs (`0/o`, `1/l`) never appear.
+ */
+declare const SHORT_LINK_TOKEN_ALPHABET = "23456789abcdefghijkmnpqrstuvwxyz";
+/** 10 characters × 5 bits = 50 bits — unguessable at any realistic probe rate. */
+declare const SHORT_LINK_TOKEN_LENGTH = 10;
+/** The resolve route on the app origin (matrx-frontend `app/(public)/r/[token]`). */
+declare const SHORT_LINK_PATH_PREFIX = "/r/";
+/**
+ * Trim, lowercase, and shape-check a candidate token. Returns the normalized
+ * token, or `null` for anything outside the contract — the resolver would
+ * refuse it anyway, so callers can skip the round trip.
+ */
+declare function normalizeShortLinkToken(candidate: string | null | undefined): string | null;
+/** Whether a string is a well-formed short-link token (after normalization). */
+declare function isShortLinkToken(candidate: string | null | undefined): boolean;
+/** The app-relative path a token resolves at: `/r/<token>`. */
+declare function shortLinkPath(token: string): string;
+/**
+ * The absolute short URL for a token on a given origin, e.g.
+ * `shortLinkUrl("https://app.aimatrx.com", token)` → `https://app.aimatrx.com/r/<token>`.
+ */
+declare function shortLinkUrl(origin: string, token: string): string;
+/** Anything with a Supabase-shaped `.rpc` — pass the Supabase client itself. */
+interface ShortLinkClient {
+    rpc(fn: string, args?: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            message: string;
+        } | null;
+    }>;
+}
+interface MintShortLinkOptions {
+    /** Same-app path to shorten (must start with a single `/`). */
+    path: string;
+    /** The organization the link belongs to — the caller must be a member. */
+    organizationId: string;
+    /** ISO timestamp; the platform default (365 days) applies when omitted. */
+    expiresAt?: string;
+    /** Origin for the returned URL; defaults to `window.location.origin`. */
+    origin?: string;
+}
+type MintShortLinkResult = {
+    ok: true;
+    token: string;
+    path: string;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Mint a short link through the platform's authenticated mint door. */
+declare function mintShortLink(client: ShortLinkClient, options: MintShortLinkOptions): Promise<MintShortLinkResult>;
+type ResolveShortLinkResult = {
+    ok: true;
+    targetPath: string;
+} | {
+    ok: false;
+};
+/**
+ * Resolve a short token to its target path through the anon resolver.
+ * `{ok:false}` covers invalid, unknown, and expired identically — the platform
+ * deliberately does not distinguish them.
+ */
+declare function resolveShortLinkPath(client: ShortLinkClient, token: string): Promise<ResolveShortLinkResult>;
+
+export { type MintShortLinkOptions, type MintShortLinkResult, type ResolveShortLinkResult, SHORT_LINK_PATH_PREFIX, SHORT_LINK_TOKEN_ALPHABET, SHORT_LINK_TOKEN_LENGTH, type ShortLinkClient, isShortLinkToken, mintShortLink, normalizeShortLinkToken, resolveShortLinkPath, shortLinkPath, shortLinkUrl };

package/dist/short-link.js

@@ -0,0 +1,76 @@
+// src/short-link.ts
+var SHORT_LINK_TOKEN_ALPHABET = "23456789abcdefghijkmnpqrstuvwxyz";
+var SHORT_LINK_TOKEN_LENGTH = 10;
+var SHORT_LINK_PATH_PREFIX = "/r/";
+var TOKEN_RE = new RegExp(`^[${SHORT_LINK_TOKEN_ALPHABET}]{${SHORT_LINK_TOKEN_LENGTH}}$`);
+function normalizeShortLinkToken(candidate) {
+  const token = (candidate ?? "").trim().toLowerCase();
+  return TOKEN_RE.test(token) ? token : null;
+}
+function isShortLinkToken(candidate) {
+  return normalizeShortLinkToken(candidate) !== null;
+}
+function shortLinkPath(token) {
+  const normalized = normalizeShortLinkToken(token);
+  if (!normalized) {
+    throw new Error(
+      `shortLinkPath: ${JSON.stringify(token)} is not a short-link token (${SHORT_LINK_TOKEN_LENGTH} chars of "${SHORT_LINK_TOKEN_ALPHABET}")`
+    );
+  }
+  return `${SHORT_LINK_PATH_PREFIX}${normalized}`;
+}
+function shortLinkUrl(origin, token) {
+  return `${origin.replace(/\/+$/, "")}${shortLinkPath(token)}`;
+}
+function resolveOrigin(origin) {
+  if (origin) return origin;
+  if (typeof window !== "undefined" && window.location?.origin) {
+    return window.location.origin;
+  }
+  return null;
+}
+async function mintShortLink(client, options) {
+  if (!options.path.startsWith("/") || options.path.startsWith("//")) {
+    return { ok: false, error: "Only a same-app path (starting with a single '/') can be shortened" };
+  }
+  const origin = resolveOrigin(options.origin);
+  if (!origin) {
+    return { ok: false, error: "No origin: pass options.origin outside a browser" };
+  }
+  const { data, error } = await client.rpc("shorten_app_url", {
+    p_path: options.path,
+    p_organization_id: options.organizationId,
+    ...options.expiresAt ? { p_expires_at: options.expiresAt } : {}
+  });
+  if (error) return { ok: false, error: error.message };
+  const result = data;
+  const token = result?.ok ? normalizeShortLinkToken(result.token) : null;
+  if (!token) {
+    return { ok: false, error: result?.error ?? "The mint door returned no token" };
+  }
+  return { ok: true, token, path: shortLinkPath(token), url: shortLinkUrl(origin, token) };
+}
+async function resolveShortLinkPath(client, token) {
+  const normalized = normalizeShortLinkToken(token);
+  if (!normalized) return { ok: false };
+  const { data, error } = await client.rpc("resolve_short_link", { p_token: normalized });
+  if (error) return { ok: false };
+  const result = data;
+  const targetPath = result?.ok ? result.target_path : void 0;
+  if (!targetPath || !targetPath.startsWith("/") || targetPath.startsWith("//")) {
+    return { ok: false };
+  }
+  return { ok: true, targetPath };
+}
+export {
+  SHORT_LINK_PATH_PREFIX,
+  SHORT_LINK_TOKEN_ALPHABET,
+  SHORT_LINK_TOKEN_LENGTH,
+  isShortLinkToken,
+  mintShortLink,
+  normalizeShortLinkToken,
+  resolveShortLinkPath,
+  shortLinkPath,
+  shortLinkUrl
+};
+//# sourceMappingURL=short-link.js.map

package/dist/short-link.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/short-link.ts"],"sourcesContent":["/**\n * @ai-matrx/kit/short-link — the platform short-link CONTRACT, in one place.\n *\n * The primitive itself lives in the database (migration `0557_platform_short_links`):\n * `platform.short_links` holds `token → same-app path`, org-scoped and expiring;\n * `platform.create_short_link` mints (server-side only); `public.resolve_short_link`\n * resolves (anon-callable; answers with a PATH, never content — the target route's\n * own auth gates everything). The frontend redirect route is `/r/[token]`\n * (matrx-frontend `app/(public)/r/[token]`), and the notification spine mints per\n * SMS leg (aidream `services/notifications/short_links.py`).\n *\n * This module is the shared vocabulary every client needs to speak about those\n * tokens — alphabet, length, validation, and the URL shape — so no consumer ever\n * re-declares it. 🚨 `SHORT_LINK_TOKEN_ALPHABET` and `SHORT_LINK_TOKEN_LENGTH`\n * mirror `platform.create_short_link` EXACTLY; change one and you change both.\n *\n * 🚨 A short link is a URL, not a permission. The primitive that grants\n * anonymous access to content is `platform.share_links` (`/s/[token]`, 64-hex\n * tokens) — a different system, deliberately. Never shorten by minting a share\n * link, and never share by minting a short link.\n *\n * Pure logic — no DOM, no React, no network; safe in Server Components, route\n * handlers, workers, and Node scripts.\n */\n\n/**\n * 32 characters: digits 2–9 plus a–z minus `l` and `o`. 256 % 32 = 0, so the\n * mint maps random bytes without modulo bias; lowercase-only survives channels\n * that case-mangle (the resolver lowercases before lookup); the ambiguous\n * glyphs (`0/o`, `1/l`) never appear.\n */\nexport const SHORT_LINK_TOKEN_ALPHABET = \"23456789abcdefghijkmnpqrstuvwxyz\";\n\n/** 10 characters × 5 bits = 50 bits — unguessable at any realistic probe rate. */\nexport const SHORT_LINK_TOKEN_LENGTH = 10;\n\n/** The resolve route on the app origin (matrx-frontend `app/(public)/r/[token]`). */\nexport const SHORT_LINK_PATH_PREFIX = \"/r/\";\n\nconst TOKEN_RE = new RegExp(`^[${SHORT_LINK_TOKEN_ALPHABET}]{${SHORT_LINK_TOKEN_LENGTH}}$`);\n\n/**\n * Trim, lowercase, and shape-check a candidate token. Returns the normalized\n * token, or `null` for anything outside the contract — the resolver would\n * refuse it anyway, so callers can skip the round trip.\n */\nexport function normalizeShortLinkToken(candidate: string | null | undefined): string | null {\n  const token = (candidate ?? \"\").trim().toLowerCase();\n  return TOKEN_RE.test(token) ? token : null;\n}\n\n/** Whether a string is a well-formed short-link token (after normalization). */\nexport function isShortLinkToken(candidate: string | null | undefined): boolean {\n  return normalizeShortLinkToken(candidate) !== null;\n}\n\n/** The app-relative path a token resolves at: `/r/<token>`. */\nexport function shortLinkPath(token: string): string {\n  const normalized = normalizeShortLinkToken(token);\n  if (!normalized) {\n    throw new Error(\n      `shortLinkPath: ${JSON.stringify(token)} is not a short-link token ` +\n        `(${SHORT_LINK_TOKEN_LENGTH} chars of \"${SHORT_LINK_TOKEN_ALPHABET}\")`,\n    );\n  }\n  return `${SHORT_LINK_PATH_PREFIX}${normalized}`;\n}\n\n/**\n * The absolute short URL for a token on a given origin, e.g.\n * `shortLinkUrl(\"https://app.aimatrx.com\", token)` → `https://app.aimatrx.com/r/<token>`.\n */\nexport function shortLinkUrl(origin: string, token: string): string {\n  return `${origin.replace(/\\/+$/, \"\")}${shortLinkPath(token)}`;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The client half — the WHOLE mint/resolve logic, so a consumer adds nothing.\n//\n// Pass your Supabase client (or anything with a compatible `.rpc`) and you are\n// done: `mintShortLink(supabase, { path, organizationId })` calls the platform's\n// authenticated mint door (`public.shorten_app_url`, org-membership-gated) and\n// hands back the finished short URL; `resolveShortLinkPath(supabase, token)`\n// calls the anon resolver (`public.resolve_short_link`). No app writes its own\n// shortener logic, ever — the only thing outside this module is the shared\n// database that stores the tokens, which is exactly where shared state lives.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/** Anything with a Supabase-shaped `.rpc` — pass the Supabase client itself. */\nexport interface ShortLinkClient {\n  rpc(\n    fn: string,\n    args?: Record<string, unknown>,\n  ): PromiseLike<{ data: unknown; error: { message: string } | null }>;\n}\n\nexport interface MintShortLinkOptions {\n  /** Same-app path to shorten (must start with a single `/`). */\n  path: string;\n  /** The organization the link belongs to — the caller must be a member. */\n  organizationId: string;\n  /** ISO timestamp; the platform default (365 days) applies when omitted. */\n  expiresAt?: string;\n  /** Origin for the returned URL; defaults to `window.location.origin`. */\n  origin?: string;\n}\n\nexport type MintShortLinkResult =\n  | { ok: true; token: string; path: string; url: string }\n  | { ok: false; error: string };\n\nfunction resolveOrigin(origin?: string): string | null {\n  if (origin) return origin;\n  if (typeof window !== \"undefined\" && window.location?.origin) {\n    return window.location.origin;\n  }\n  return null;\n}\n\n/** Mint a short link through the platform's authenticated mint door. */\nexport async function mintShortLink(\n  client: ShortLinkClient,\n  options: MintShortLinkOptions,\n): Promise<MintShortLinkResult> {\n  if (!options.path.startsWith(\"/\") || options.path.startsWith(\"//\")) {\n    return { ok: false, error: \"Only a same-app path (starting with a single '/') can be shortened\" };\n  }\n  const origin = resolveOrigin(options.origin);\n  if (!origin) {\n    return { ok: false, error: \"No origin: pass options.origin outside a browser\" };\n  }\n  const { data, error } = await client.rpc(\"shorten_app_url\", {\n    p_path: options.path,\n    p_organization_id: options.organizationId,\n    ...(options.expiresAt ? { p_expires_at: options.expiresAt } : {}),\n  });\n  if (error) return { ok: false, error: error.message };\n  const result = data as { ok?: boolean; token?: string; error?: string } | null;\n  const token = result?.ok ? normalizeShortLinkToken(result.token) : null;\n  if (!token) {\n    return { ok: false, error: result?.error ?? \"The mint door returned no token\" };\n  }\n  return { ok: true, token, path: shortLinkPath(token), url: shortLinkUrl(origin, token) };\n}\n\nexport type ResolveShortLinkResult =\n  | { ok: true; targetPath: string }\n  | { ok: false };\n\n/**\n * Resolve a short token to its target path through the anon resolver.\n * `{ok:false}` covers invalid, unknown, and expired identically — the platform\n * deliberately does not distinguish them.\n */\nexport async function resolveShortLinkPath(\n  client: ShortLinkClient,\n  token: string,\n): Promise<ResolveShortLinkResult> {\n  const normalized = normalizeShortLinkToken(token);\n  if (!normalized) return { ok: false };\n  const { data, error } = await client.rpc(\"resolve_short_link\", { p_token: normalized });\n  if (error) return { ok: false };\n  const result = data as { ok?: boolean; target_path?: string } | null;\n  const targetPath = result?.ok ? result.target_path : undefined;\n  if (!targetPath || !targetPath.startsWith(\"/\") || targetPath.startsWith(\"//\")) {\n    return { ok: false };\n  }\n  return { ok: true, targetPath };\n}\n"],"mappings":";AA+BO,IAAM,4BAA4B;AAGlC,IAAM,0BAA0B;AAGhC,IAAM,yBAAyB;AAEtC,IAAM,WAAW,IAAI,OAAO,KAAK,yBAAyB,KAAK,uBAAuB,IAAI;AAOnF,SAAS,wBAAwB,WAAqD;AAC3F,QAAM,SAAS,aAAa,IAAI,KAAK,EAAE,YAAY;AACnD,SAAO,SAAS,KAAK,KAAK,IAAI,QAAQ;AACxC;AAGO,SAAS,iBAAiB,WAA+C;AAC9E,SAAO,wBAAwB,SAAS,MAAM;AAChD;AAGO,SAAS,cAAc,OAAuB;AACnD,QAAM,aAAa,wBAAwB,KAAK;AAChD,MAAI,CAAC,YAAY;AACf,UAAM,IAAI;AAAA,MACR,kBAAkB,KAAK,UAAU,KAAK,CAAC,+BACjC,uBAAuB,cAAc,yBAAyB;AAAA,IACtE;AAAA,EACF;AACA,SAAO,GAAG,sBAAsB,GAAG,UAAU;AAC/C;AAMO,SAAS,aAAa,QAAgB,OAAuB;AAClE,SAAO,GAAG,OAAO,QAAQ,QAAQ,EAAE,CAAC,GAAG,cAAc,KAAK,CAAC;AAC7D;AAqCA,SAAS,cAAc,QAAgC;AACrD,MAAI,OAAQ,QAAO;AACnB,MAAI,OAAO,WAAW,eAAe,OAAO,UAAU,QAAQ;AAC5D,WAAO,OAAO,SAAS;AAAA,EACzB;AACA,SAAO;AACT;AAGA,eAAsB,cACpB,QACA,SAC8B;AAC9B,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG,KAAK,QAAQ,KAAK,WAAW,IAAI,GAAG;AAClE,WAAO,EAAE,IAAI,OAAO,OAAO,qEAAqE;AAAA,EAClG;AACA,QAAM,SAAS,cAAc,QAAQ,MAAM;AAC3C,MAAI,CAAC,QAAQ;AACX,WAAO,EAAE,IAAI,OAAO,OAAO,mDAAmD;AAAA,EAChF;AACA,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,mBAAmB;AAAA,IAC1D,QAAQ,QAAQ;AAAA,IAChB,mBAAmB,QAAQ;AAAA,IAC3B,GAAI,QAAQ,YAAY,EAAE,cAAc,QAAQ,UAAU,IAAI,CAAC;AAAA,EACjE,CAAC;AACD,MAAI,MAAO,QAAO,EAAE,IAAI,OAAO,OAAO,MAAM,QAAQ;AACpD,QAAM,SAAS;AACf,QAAM,QAAQ,QAAQ,KAAK,wBAAwB,OAAO,KAAK,IAAI;AACnE,MAAI,CAAC,OAAO;AACV,WAAO,EAAE,IAAI,OAAO,OAAO,QAAQ,SAAS,kCAAkC;AAAA,EAChF;AACA,SAAO,EAAE,IAAI,MAAM,OAAO,MAAM,cAAc,KAAK,GAAG,KAAK,aAAa,QAAQ,KAAK,EAAE;AACzF;AAWA,eAAsB,qBACpB,QACA,OACiC;AACjC,QAAM,aAAa,wBAAwB,KAAK;AAChD,MAAI,CAAC,WAAY,QAAO,EAAE,IAAI,MAAM;AACpC,QAAM,EAAE,MAAM,MAAM,IAAI,MAAM,OAAO,IAAI,sBAAsB,EAAE,SAAS,WAAW,CAAC;AACtF,MAAI,MAAO,QAAO,EAAE,IAAI,MAAM;AAC9B,QAAM,SAAS;AACf,QAAM,aAAa,QAAQ,KAAK,OAAO,cAAc;AACrD,MAAI,CAAC,cAAc,CAAC,WAAW,WAAW,GAAG,KAAK,WAAW,WAAW,IAAI,GAAG;AAC7E,WAAO,EAAE,IAAI,MAAM;AAAA,EACrB;AACA,SAAO,EAAE,IAAI,MAAM,WAAW;AAChC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/kit",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "The always-include AI Matrx kit: the little primitives every Matrx app speaks — autosave that never loses a keystroke, stale-response guards, clipboard with graceful fallbacks — one per subpath, tree-shaken to what you use.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,7 +21,8 @@
     "markdown-streaming",
     "indexeddb",
     "tailwind-colors",
-    "qr-code"
+    "qr-code",
+    "short-link"
   ],
   "repository": {
     "type": "git",
@@ -239,6 +240,26 @@
         "types": "./dist/qr.d.cts",
         "default": "./dist/qr.cjs"
       }
+    },
+    "./short-link": {
+      "import": {
+        "types": "./dist/short-link.d.ts",
+        "default": "./dist/short-link.js"
+      },
+      "require": {
+        "types": "./dist/short-link.d.cts",
+        "default": "./dist/short-link.cjs"
+      }
+    },
+    "./short-link-react": {
+      "import": {
+        "types": "./dist/short-link-react.d.ts",
+        "default": "./dist/short-link-react.js"
+      },
+      "require": {
+        "types": "./dist/short-link-react.d.cts",
+        "default": "./dist/short-link-react.cjs"
+      }
     }
   },
   "dependencies": {