@vosjs/shared 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/shared",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The small shared layer under the vos CLI and the vosso studio: the semantic differ, the free-tier limits, frontmatter, params, the font and typeface catalogs.",
   "license": "MIT",
   "author": "vosso",
@@ -45,14 +45,6 @@
       "types": "./dist/limits.d.ts",
       "import": "./dist/limits.js"
     },
-    "./acquisition": {
-      "types": "./dist/acquisition.d.ts",
-      "import": "./dist/acquisition.js"
-    },
-    "./backdrops": {
-      "types": "./dist/backdrops.d.ts",
-      "import": "./dist/backdrops.js"
-    },
     "./timelineEdits": {
       "types": "./dist/timelineEdits.d.ts",
       "import": "./dist/timelineEdits.js"

package/dist/acquisition.d.ts

@@ -1,59 +0,0 @@
-/**
- * Signup attribution (first touch), pure.
- *
- * PostHog already sees every referrer and utm param, but nothing first-party
- * survives to the `user` row, and a first touch is the one fact that can
- * never be backfilled. The seam is deliberately tiny: a write-once cookie set
- * by the web worker on the first arrival that carries a signal (an external
- * referrer or utm params — a direct visit sets nothing), read exactly once
- * when BetterAuth creates the user, then stamped as JSON on
- * `user.acquisition` and never updated.
- *
- * Everything here is pure so the platform's cookie writer and its signup
- * reader can never disagree on the format.
- */
-declare const FIRST_TOUCH_COOKIE = "vosso_ft";
-/** 30 days: long enough to span consider-then-signup, short enough to stay a
- *  first touch rather than a biography. */
-declare const FIRST_TOUCH_MAX_AGE: number;
-interface FirstTouch {
-    /** utm_source, or the referring domain when the arrival was untagged. */
-    source: string;
-    /** utm_medium, or 'referral' when derived from a bare referrer. */
-    medium?: string;
-    /** utm_campaign, verbatim. */
-    campaign?: string;
-    /** External referring domain, when there was one. */
-    referrer?: string;
-    /** The path the visit landed on. */
-    landing?: string;
-    /** ISO timestamp of the first touch. */
-    at?: string;
-}
-/**
- * Derive a first touch from a landing request, or null when the visit
- * carries no acquisition signal. Null is the common case and the point:
- * a direct visit gets no cookie, and an absent `user.acquisition` reads
- * honestly as "direct or before the feature", never as a guessed channel.
- */
-declare function firstTouchOf(input: {
-    url: URL;
-    referer: string | null | undefined;
-}): FirstTouch | null;
-/** Cookie-safe encoding of a first touch. */
-declare function encodeFirstTouch(touch: FirstTouch): string;
-/**
- * Fail-closed parse of first-touch JSON (the shape `user.acquisition`
- * stores): anything oversized, unparseable, or missing a string `source`
- * is null.
- */
-declare function parseFirstTouchJson(raw: string | null | undefined): FirstTouch | null;
-/**
- * Fail-closed cookie decode. The cookie arrives from the wild — a browser
- * extension or a hand-edited jar can put anything under our name.
- */
-declare function decodeFirstTouch(raw: string | null | undefined): FirstTouch | null;
-/** Read one cookie's raw value out of a Cookie header. */
-declare function readCookieValue(header: string | null | undefined, name: string): string | undefined;
-
-export { FIRST_TOUCH_COOKIE, FIRST_TOUCH_MAX_AGE, type FirstTouch, decodeFirstTouch, encodeFirstTouch, firstTouchOf, parseFirstTouchJson, readCookieValue };

package/dist/acquisition.js

@@ -1,92 +0,0 @@
-// src/acquisition.ts
-var FIRST_TOUCH_COOKIE = "vosso_ft";
-var FIRST_TOUCH_MAX_AGE = 60 * 60 * 24 * 30;
-var FIELD_MAX = 200;
-var RAW_MAX = 2e3;
-function clean(value) {
-  const v = value?.trim().slice(0, FIELD_MAX);
-  return v || void 0;
-}
-function sameSite(a, b) {
-  const strip = (h) => h.startsWith("www.") ? h.slice(4) : h;
-  return strip(a) === strip(b);
-}
-function firstTouchOf(input) {
-  const { url, referer } = input;
-  const source = clean(url.searchParams.get("utm_source"));
-  const medium = clean(url.searchParams.get("utm_medium"));
-  const campaign = clean(url.searchParams.get("utm_campaign"));
-  let referrerDomain;
-  if (referer) {
-    try {
-      const r = new URL(referer);
-      if (r.hostname && !sameSite(r.hostname, url.hostname)) {
-        referrerDomain = clean(r.hostname);
-      }
-    } catch {
-    }
-  }
-  if (!source && !campaign && !referrerDomain) return null;
-  const touch = {
-    source: source ?? referrerDomain ?? "unknown"
-  };
-  const derivedMedium = medium ?? (!source && referrerDomain ? "referral" : void 0);
-  if (derivedMedium) touch.medium = derivedMedium;
-  if (campaign) touch.campaign = campaign;
-  if (referrerDomain) touch.referrer = referrerDomain;
-  return touch;
-}
-function encodeFirstTouch(touch) {
-  return encodeURIComponent(JSON.stringify(touch));
-}
-function parseFirstTouchJson(raw) {
-  if (!raw || raw.length > RAW_MAX) return null;
-  try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed !== "object" || parsed === null) return null;
-    const record = parsed;
-    if (typeof record.source !== "string" || !record.source) return null;
-    const touch = { source: record.source.slice(0, FIELD_MAX) };
-    for (const key of [
-      "medium",
-      "campaign",
-      "referrer",
-      "landing",
-      "at"
-    ]) {
-      const value = record[key];
-      if (typeof value === "string" && value)
-        touch[key] = value.slice(0, FIELD_MAX);
-    }
-    return touch;
-  } catch {
-    return null;
-  }
-}
-function decodeFirstTouch(raw) {
-  if (!raw || raw.length > RAW_MAX) return null;
-  try {
-    return parseFirstTouchJson(decodeURIComponent(raw));
-  } catch {
-    return null;
-  }
-}
-function readCookieValue(header, name) {
-  if (!header) return void 0;
-  for (const part of header.split(";")) {
-    const eq = part.indexOf("=");
-    if (eq === -1) continue;
-    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
-  }
-  return void 0;
-}
-export {
-  FIRST_TOUCH_COOKIE,
-  FIRST_TOUCH_MAX_AGE,
-  decodeFirstTouch,
-  encodeFirstTouch,
-  firstTouchOf,
-  parseFirstTouchJson,
-  readCookieValue
-};
-//# sourceMappingURL=acquisition.js.map

package/dist/acquisition.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/acquisition.ts"],"sourcesContent":["/**\n * Signup attribution (first touch), pure.\n *\n * PostHog already sees every referrer and utm param, but nothing first-party\n * survives to the `user` row, and a first touch is the one fact that can\n * never be backfilled. The seam is deliberately tiny: a write-once cookie set\n * by the web worker on the first arrival that carries a signal (an external\n * referrer or utm params — a direct visit sets nothing), read exactly once\n * when BetterAuth creates the user, then stamped as JSON on\n * `user.acquisition` and never updated.\n *\n * Everything here is pure so the platform's cookie writer and its signup\n * reader can never disagree on the format.\n */\n\nexport const FIRST_TOUCH_COOKIE = 'vosso_ft'\n\n/** 30 days: long enough to span consider-then-signup, short enough to stay a\n *  first touch rather than a biography. */\nexport const FIRST_TOUCH_MAX_AGE = 60 * 60 * 24 * 30\n\n/** Per-field cap. UTM values are short by convention; anything longer is\n *  noise or abuse and gets truncated rather than refused. */\nconst FIELD_MAX = 200\n\n/** Decode guard: a cookie bigger than this is not ours. */\nconst RAW_MAX = 2000\n\nexport interface FirstTouch {\n  /** utm_source, or the referring domain when the arrival was untagged. */\n  source: string\n  /** utm_medium, or 'referral' when derived from a bare referrer. */\n  medium?: string\n  /** utm_campaign, verbatim. */\n  campaign?: string\n  /** External referring domain, when there was one. */\n  referrer?: string\n  /** The path the visit landed on. */\n  landing?: string\n  /** ISO timestamp of the first touch. */\n  at?: string\n}\n\nfunction clean(value: string | null | undefined): string | undefined {\n  const v = value?.trim().slice(0, FIELD_MAX)\n  return v || undefined\n}\n\n/**\n * Is the referrer an internal navigation rather than an arrival? Compares\n * registrable-host-ish: `www.vos.so` referring to `vos.so` is the same site\n * (canonicalHost 301s www onto the apex, so the second request's referrer is\n * our own www host and must not read as a referral).\n */\nfunction sameSite(a: string, b: string): boolean {\n  const strip = (h: string) => (h.startsWith('www.') ? h.slice(4) : h)\n  return strip(a) === strip(b)\n}\n\n/**\n * Derive a first touch from a landing request, or null when the visit\n * carries no acquisition signal. Null is the common case and the point:\n * a direct visit gets no cookie, and an absent `user.acquisition` reads\n * honestly as \"direct or before the feature\", never as a guessed channel.\n */\nexport function firstTouchOf(input: {\n  url: URL\n  referer: string | null | undefined\n}): FirstTouch | null {\n  const { url, referer } = input\n  const source = clean(url.searchParams.get('utm_source'))\n  const medium = clean(url.searchParams.get('utm_medium'))\n  const campaign = clean(url.searchParams.get('utm_campaign'))\n\n  let referrerDomain: string | undefined\n  if (referer) {\n    try {\n      const r = new URL(referer)\n      if (r.hostname && !sameSite(r.hostname, url.hostname)) {\n        referrerDomain = clean(r.hostname)\n      }\n    } catch {\n      // An unparseable referrer is no signal.\n    }\n  }\n\n  if (!source && !campaign && !referrerDomain) return null\n\n  const touch: FirstTouch = {\n    source: source ?? referrerDomain ?? 'unknown',\n  }\n  const derivedMedium =\n    medium ?? (!source && referrerDomain ? 'referral' : undefined)\n  if (derivedMedium) touch.medium = derivedMedium\n  if (campaign) touch.campaign = campaign\n  if (referrerDomain) touch.referrer = referrerDomain\n  return touch\n}\n\n/** Cookie-safe encoding of a first touch. */\nexport function encodeFirstTouch(touch: FirstTouch): string {\n  return encodeURIComponent(JSON.stringify(touch))\n}\n\n/**\n * Fail-closed parse of first-touch JSON (the shape `user.acquisition`\n * stores): anything oversized, unparseable, or missing a string `source`\n * is null.\n */\nexport function parseFirstTouchJson(\n  raw: string | null | undefined,\n): FirstTouch | null {\n  if (!raw || raw.length > RAW_MAX) return null\n  try {\n    const parsed: unknown = JSON.parse(raw)\n    if (typeof parsed !== 'object' || parsed === null) return null\n    const record = parsed as Record<string, unknown>\n    if (typeof record.source !== 'string' || !record.source) return null\n    const touch: FirstTouch = { source: record.source.slice(0, FIELD_MAX) }\n    for (const key of [\n      'medium',\n      'campaign',\n      'referrer',\n      'landing',\n      'at',\n    ] as const) {\n      const value = record[key]\n      if (typeof value === 'string' && value)\n        touch[key] = value.slice(0, FIELD_MAX)\n    }\n    return touch\n  } catch {\n    return null\n  }\n}\n\n/**\n * Fail-closed cookie decode. The cookie arrives from the wild — a browser\n * extension or a hand-edited jar can put anything under our name.\n */\nexport function decodeFirstTouch(\n  raw: string | null | undefined,\n): FirstTouch | null {\n  if (!raw || raw.length > RAW_MAX) return null\n  try {\n    return parseFirstTouchJson(decodeURIComponent(raw))\n  } catch {\n    return null\n  }\n}\n\n/** Read one cookie's raw value out of a Cookie header. */\nexport function readCookieValue(\n  header: string | null | undefined,\n  name: string,\n): string | undefined {\n  if (!header) return undefined\n  for (const part of header.split(';')) {\n    const eq = part.indexOf('=')\n    if (eq === -1) continue\n    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim()\n  }\n  return undefined\n}\n"],"mappings":";AAeO,IAAM,qBAAqB;AAI3B,IAAM,sBAAsB,KAAK,KAAK,KAAK;AAIlD,IAAM,YAAY;AAGlB,IAAM,UAAU;AAiBhB,SAAS,MAAM,OAAsD;AACnE,QAAM,IAAI,OAAO,KAAK,EAAE,MAAM,GAAG,SAAS;AAC1C,SAAO,KAAK;AACd;AAQA,SAAS,SAAS,GAAW,GAAoB;AAC/C,QAAM,QAAQ,CAAC,MAAe,EAAE,WAAW,MAAM,IAAI,EAAE,MAAM,CAAC,IAAI;AAClE,SAAO,MAAM,CAAC,MAAM,MAAM,CAAC;AAC7B;AAQO,SAAS,aAAa,OAGP;AACpB,QAAM,EAAE,KAAK,QAAQ,IAAI;AACzB,QAAM,SAAS,MAAM,IAAI,aAAa,IAAI,YAAY,CAAC;AACvD,QAAM,SAAS,MAAM,IAAI,aAAa,IAAI,YAAY,CAAC;AACvD,QAAM,WAAW,MAAM,IAAI,aAAa,IAAI,cAAc,CAAC;AAE3D,MAAI;AACJ,MAAI,SAAS;AACX,QAAI;AACF,YAAM,IAAI,IAAI,IAAI,OAAO;AACzB,UAAI,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,IAAI,QAAQ,GAAG;AACrD,yBAAiB,MAAM,EAAE,QAAQ;AAAA,MACnC;AAAA,IACF,QAAQ;AAAA,IAER;AAAA,EACF;AAEA,MAAI,CAAC,UAAU,CAAC,YAAY,CAAC,eAAgB,QAAO;AAEpD,QAAM,QAAoB;AAAA,IACxB,QAAQ,UAAU,kBAAkB;AAAA,EACtC;AACA,QAAM,gBACJ,WAAW,CAAC,UAAU,iBAAiB,aAAa;AACtD,MAAI,cAAe,OAAM,SAAS;AAClC,MAAI,SAAU,OAAM,WAAW;AAC/B,MAAI,eAAgB,OAAM,WAAW;AACrC,SAAO;AACT;AAGO,SAAS,iBAAiB,OAA2B;AAC1D,SAAO,mBAAmB,KAAK,UAAU,KAAK,CAAC;AACjD;AAOO,SAAS,oBACd,KACmB;AACnB,MAAI,CAAC,OAAO,IAAI,SAAS,QAAS,QAAO;AACzC,MAAI;AACF,UAAM,SAAkB,KAAK,MAAM,GAAG;AACtC,QAAI,OAAO,WAAW,YAAY,WAAW,KAAM,QAAO;AAC1D,UAAM,SAAS;AACf,QAAI,OAAO,OAAO,WAAW,YAAY,CAAC,OAAO,OAAQ,QAAO;AAChE,UAAM,QAAoB,EAAE,QAAQ,OAAO,OAAO,MAAM,GAAG,SAAS,EAAE;AACtE,eAAW,OAAO;AAAA,MAChB;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,GAAY;AACV,YAAM,QAAQ,OAAO,GAAG;AACxB,UAAI,OAAO,UAAU,YAAY;AAC/B,cAAM,GAAG,IAAI,MAAM,MAAM,GAAG,SAAS;AAAA,IACzC;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAMO,SAAS,iBACd,KACmB;AACnB,MAAI,CAAC,OAAO,IAAI,SAAS,QAAS,QAAO;AACzC,MAAI;AACF,WAAO,oBAAoB,mBAAmB,GAAG,CAAC;AAAA,EACpD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,SAAS,gBACd,QACA,MACoB;AACpB,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAW,QAAQ,OAAO,MAAM,GAAG,GAAG;AACpC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,OAAO,GAAI;AACf,QAAI,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK,MAAM,KAAM,QAAO,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK;AAAA,EACxE;AACA,SAAO;AACT;","names":[]}

package/dist/backdrops.d.ts

@@ -1,29 +0,0 @@
-/**
- * The backdrop wire contract: what `GET /api/backdrops`
- * hands to the studio panel, the picker, the CLI and agents. Absolute URLs
- * on purpose — a ProjectDoc travels across environments (save-to-vos, CLI
- * takes, server renders), so a backdrop key must resolve everywhere without
- * host-side rewriting.
- */
-declare const BACKDROP_ASSET_BASE = "https://assets.vos.so/";
-interface Backdrop {
-    id: string;
-    slug: string;
-    title: string;
-    /** The loop's length in seconds — a fact of the asset, never a knob. */
-    duration: number;
-    /** The 1080p bake's pixel size (the export note reads it). */
-    width: number;
-    height: number;
-    /** The CSS underlay a pick writes into `frame.background`. */
-    ground: string;
-    /** Provenance: the vos it was baked from, when it still exists. */
-    vosId: string | null;
-    urls: {
-        '1080p': string | null;
-        '2k': string | null;
-        poster: string | null;
-    };
-}
-
-export { BACKDROP_ASSET_BASE, type Backdrop };

package/dist/backdrops.js

@@ -1,6 +0,0 @@
-// src/backdrops.ts
-var BACKDROP_ASSET_BASE = "https://assets.vos.so/";
-export {
-  BACKDROP_ASSET_BASE
-};
-//# sourceMappingURL=backdrops.js.map

package/dist/backdrops.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/backdrops.ts"],"sourcesContent":["/**\n * The backdrop wire contract: what `GET /api/backdrops`\n * hands to the studio panel, the picker, the CLI and agents. Absolute URLs\n * on purpose — a ProjectDoc travels across environments (save-to-vos, CLI\n * takes, server renders), so a backdrop key must resolve everywhere without\n * host-side rewriting.\n */\n\nexport const BACKDROP_ASSET_BASE = 'https://assets.vos.so/'\n\nexport interface Backdrop {\n  id: string\n  slug: string\n  title: string\n  /** The loop's length in seconds — a fact of the asset, never a knob. */\n  duration: number\n  /** The 1080p bake's pixel size (the export note reads it). */\n  width: number\n  height: number\n  /** The CSS underlay a pick writes into `frame.background`. */\n  ground: string\n  /** Provenance: the vos it was baked from, when it still exists. */\n  vosId: string | null\n  urls: {\n    '1080p': string | null\n    '2k': string | null\n    poster: string | null\n  }\n}\n"],"mappings":";AAQO,IAAM,sBAAsB;","names":[]}