@open-feishu-card/store 0.1.0

package/dist/codec.d.ts

@@ -0,0 +1,22 @@
+/** fragment 协议版本：s1 = JSON → UTF-8 → deflate → base64url */
+export declare const STATE_CODEC_VERSION: 's1';
+/** 跳转基座：即使被点到也不会打开网页 */
+export declare const STATE_URL_BASE = "lark://msgcard/unsupported_action";
+/** 完整 URL 前缀（含 #） */
+export declare const STATE_URL_PREFIX: "lark://msgcard/unsupported_action#";
+export declare class StateCodecError extends Error {
+    constructor(message: string);
+}
+/**
+ * 把任意 JSON 可序列化值编码为完整封印 URL。
+ * 格式：`lark://msgcard/unsupported_action#s1.<base64url(deflate(json))>`
+ */
+export declare function encodeStateUrl(state: unknown): string;
+/**
+ * 从封印 URL（或裸 fragment / 带版本前缀的 payload）解码 state。
+ * 无法识别或损坏时返回 null。
+ */
+export declare function decodeStateUrl(urlOrFragment: string): unknown | null;
+/** 判断字符串是否为我们的封印 URL / fragment */
+export declare function isStateUrl(value: string): boolean;
+//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAEA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,EAAG,IAAa,CAAC;AAEjD,wBAAwB;AACxB,eAAO,MAAM,cAAc,sCAAsC,CAAC;AAElE,qBAAqB;AACrB,eAAO,MAAM,gBAAgB,sCAAgC,CAAC;AAE9D,qBAAa,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAerD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA2BpE;AAED,mCAAmC;AACnC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAUjD"}

package/dist/host.d.ts

@@ -0,0 +1,22 @@
+/** 专用空分栏宿主的 element_id（写入时保证；飞书/adapter 回读可能丢掉） */
+export declare const STATE_ELEMENT_ID = "card_state";
+/** 构造专用空分栏宿主（只写 url，避免 4 份复制吃额度） */
+export declare function createStateHost(stateUrl: string): Record<string, unknown>;
+/** 在卡片上查找 state 宿主 column_set */
+export declare function findStateHost(card: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * 从卡片读取封印 state（不改卡）。
+ * 兼容：DSL `action.multi_url`、adapter 投影的 `actions[]`、RAW `property.actions`。
+ */
+export declare function readCardState<T = unknown>(card: Record<string, unknown>): T | null;
+/**
+ * 把 state 封印进卡片：写入/更新空分栏 `card_state` 的 `action.multi_url.url`。
+ * 就地修改 card；返回编码后的 URL。
+ */
+export declare function sealCardState(card: Record<string, unknown>, state: unknown): string;
+/**
+ * 读取并移除宿主分栏（可选，用于迁移）。
+ * 返回解码到的 state；没有则 null。
+ */
+export declare function unsealCardState<T = unknown>(card: Record<string, unknown>): T | null;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAOA,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AA6E7C,oCAAoC;AACpC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzE;AAgBD,iCAAiC;AACjC,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAO3F;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAkClF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAUnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAOpF"}

package/dist/index.cjs

@@ -0,0 +1,221 @@
+'use strict';
+
+var zlib = require('zlib');
+
+// src/codec.ts
+var STATE_CODEC_VERSION = "s1";
+var STATE_URL_BASE = "lark://msgcard/unsupported_action";
+var STATE_URL_PREFIX = `${STATE_URL_BASE}#`;
+var StateCodecError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StateCodecError";
+  }
+};
+function encodeStateUrl(state) {
+  let json;
+  try {
+    json = JSON.stringify(state);
+  } catch (err) {
+    throw new StateCodecError(
+      `state \u65E0\u6CD5 JSON \u5E8F\u5217\u5316: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (json === void 0) {
+    throw new StateCodecError("state \u65E0\u6CD5 JSON \u5E8F\u5217\u5316\uFF08undefined\uFF09");
+  }
+  const compressed = zlib.deflateSync(Buffer.from(json, "utf8"), { level: 9 });
+  const payload = compressed.toString("base64url");
+  return `${STATE_URL_PREFIX}${STATE_CODEC_VERSION}.${payload}`;
+}
+function decodeStateUrl(urlOrFragment) {
+  if (typeof urlOrFragment !== "string" || !urlOrFragment) return null;
+  let fragment = urlOrFragment;
+  const hash = urlOrFragment.indexOf("#");
+  if (hash >= 0) {
+    fragment = urlOrFragment.slice(hash + 1);
+  }
+  const dot = fragment.indexOf(".");
+  if (dot <= 0) return null;
+  const version = fragment.slice(0, dot);
+  const payload = fragment.slice(dot + 1);
+  if (!payload) return null;
+  if (version === STATE_CODEC_VERSION) {
+    try {
+      const raw = Buffer.from(payload, "base64url");
+      const json = zlib.inflateSync(raw).toString("utf8");
+      return JSON.parse(json);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function isStateUrl(value) {
+  if (typeof value !== "string" || !value) return false;
+  if (value.startsWith(STATE_URL_PREFIX)) {
+    return decodeStateUrl(value) !== null;
+  }
+  if (value.startsWith(`${STATE_CODEC_VERSION}.`)) {
+    return decodeStateUrl(value) !== null;
+  }
+  return false;
+}
+
+// src/host.ts
+var STATE_ELEMENT_ID = "card_state";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function walk(node, visit, parent = null) {
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit, parent);
+    return;
+  }
+  if (!isRecord(node)) return;
+  visit(node, parent);
+  for (const value of Object.values(node)) walk(value, visit, node);
+}
+function extractStateUrl(node) {
+  const action = node.action;
+  if (isRecord(action)) {
+    const multi = action.multi_url;
+    if (isRecord(multi) && typeof multi.url === "string" && isStateUrl(multi.url)) {
+      return multi.url;
+    }
+    if (typeof action.url === "string" && isStateUrl(action.url)) {
+      return action.url;
+    }
+  }
+  if (Array.isArray(node.actions)) {
+    for (const item of node.actions) {
+      if (!isRecord(item)) continue;
+      const inner = isRecord(item.action) ? item.action : item;
+      for (const key of ["url", "default_url", "pc_url", "ios_url", "android_url", "pcURL", "iosURL", "androidURL"]) {
+        const v = inner[key];
+        if (typeof v === "string" && isStateUrl(v)) return v;
+      }
+    }
+  }
+  const property = node.property;
+  if (isRecord(property) && Array.isArray(property.actions)) {
+    for (const item of property.actions) {
+      if (!isRecord(item)) continue;
+      const inner = isRecord(item.action) ? item.action : item;
+      for (const key of ["url", "pcURL", "iosURL", "androidURL"]) {
+        const v = inner[key];
+        if (typeof v === "string" && isStateUrl(v)) return v;
+      }
+    }
+  }
+  if (isRecord(node.multi_url) && typeof node.multi_url.url === "string" && isStateUrl(node.multi_url.url)) {
+    return node.multi_url.url;
+  }
+  return null;
+}
+function isStateHost(node) {
+  if (node.tag === "column_set" && node.element_id === STATE_ELEMENT_ID) return true;
+  if (node.tag === "column_set" && node.id === STATE_ELEMENT_ID) return true;
+  if (node.tag === "column_set" && extractStateUrl(node)) return true;
+  if (node.id === STATE_ELEMENT_ID && extractStateUrl(node)) return true;
+  return false;
+}
+function createStateHost(stateUrl) {
+  return {
+    tag: "column_set",
+    element_id: STATE_ELEMENT_ID,
+    action: {
+      multi_url: {
+        url: stateUrl
+      }
+    },
+    columns: [
+      {
+        tag: "column",
+        width: "auto",
+        elements: []
+      }
+    ]
+  };
+}
+function ensureBodyElements(card) {
+  const existing = card.body;
+  const body = isRecord(existing) ? existing : { elements: [] };
+  if (!isRecord(existing)) {
+    card.body = body;
+  }
+  if (!Array.isArray(body.elements)) {
+    body.elements = [];
+  }
+  return body.elements;
+}
+function findStateHost(card) {
+  let found = null;
+  walk(card, (obj) => {
+    if (found) return;
+    if (isStateHost(obj)) found = obj;
+  });
+  return found;
+}
+function readCardState(card) {
+  const host = findStateHost(card);
+  if (host) {
+    const url = extractStateUrl(host);
+    if (url) {
+      const state = decodeStateUrl(url);
+      return state;
+    }
+  }
+  let decoded = null;
+  walk(card, (obj) => {
+    if (decoded !== null) return;
+    const url = extractStateUrl(obj);
+    if (url) decoded = decodeStateUrl(url);
+  });
+  if (decoded === null) {
+    walk(card, (obj) => {
+      if (decoded !== null) return;
+      for (const v of Object.values(obj)) {
+        if (typeof v === "string" && v.startsWith(STATE_URL_PREFIX)) {
+          const s = decodeStateUrl(v);
+          if (s !== null) {
+            decoded = s;
+            return;
+          }
+        }
+      }
+    });
+  }
+  return decoded;
+}
+function sealCardState(card, state) {
+  const stateUrl = encodeStateUrl(state);
+  const elements = ensureBodyElements(card);
+  const next = elements.filter((el) => !(isRecord(el) && isStateHost(el)));
+  next.push(createStateHost(stateUrl));
+  const body = card.body;
+  body.elements = next;
+  return stateUrl;
+}
+function unsealCardState(card) {
+  const state = readCardState(card);
+  const body = isRecord(card.body) ? card.body : null;
+  if (body && Array.isArray(body.elements)) {
+    body.elements = body.elements.filter((el) => !(isRecord(el) && isStateHost(el)));
+  }
+  return state;
+}
+
+exports.STATE_CODEC_VERSION = STATE_CODEC_VERSION;
+exports.STATE_ELEMENT_ID = STATE_ELEMENT_ID;
+exports.STATE_URL_BASE = STATE_URL_BASE;
+exports.STATE_URL_PREFIX = STATE_URL_PREFIX;
+exports.StateCodecError = StateCodecError;
+exports.createStateHost = createStateHost;
+exports.decodeStateUrl = decodeStateUrl;
+exports.encodeStateUrl = encodeStateUrl;
+exports.findStateHost = findStateHost;
+exports.isStateUrl = isStateUrl;
+exports.readCardState = readCardState;
+exports.sealCardState = sealCardState;
+exports.unsealCardState = unsealCardState;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @open-feishu-card/store
+ *
+ * 卡片内嵌 state：空 `column_set`（零高度）+ `action.multi_url.url`，
+ * 载荷为 `deflate → base64url`。
+ *
+ * 写入形态（DSL）：
+ * ```json
+ * {
+ *   "tag": "column_set",
+ *   "element_id": "card_state",
+ *   "action": { "multi_url": { "url": "lark://msgcard/unsupported_action#s1...." } },
+ *   "columns": [{ "tag": "column", "width": "auto", "elements": [] }]
+ * }
+ * ```
+ *
+ * 回读请走 `raw_card_content`（`user_card_content` 会丢掉 URL）。
+ */
+export { STATE_CODEC_VERSION, STATE_URL_BASE, STATE_URL_PREFIX, StateCodecError, encodeStateUrl, decodeStateUrl, isStateUrl, } from './codec.js';
+export { STATE_ELEMENT_ID, createStateHost, findStateHost, readCardState, sealCardState, unsealCardState, } from './host.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,cAAc,EACd,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,207 @@
+import { deflateSync, inflateSync } from 'zlib';
+
+// src/codec.ts
+var STATE_CODEC_VERSION = "s1";
+var STATE_URL_BASE = "lark://msgcard/unsupported_action";
+var STATE_URL_PREFIX = `${STATE_URL_BASE}#`;
+var StateCodecError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StateCodecError";
+  }
+};
+function encodeStateUrl(state) {
+  let json;
+  try {
+    json = JSON.stringify(state);
+  } catch (err) {
+    throw new StateCodecError(
+      `state \u65E0\u6CD5 JSON \u5E8F\u5217\u5316: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (json === void 0) {
+    throw new StateCodecError("state \u65E0\u6CD5 JSON \u5E8F\u5217\u5316\uFF08undefined\uFF09");
+  }
+  const compressed = deflateSync(Buffer.from(json, "utf8"), { level: 9 });
+  const payload = compressed.toString("base64url");
+  return `${STATE_URL_PREFIX}${STATE_CODEC_VERSION}.${payload}`;
+}
+function decodeStateUrl(urlOrFragment) {
+  if (typeof urlOrFragment !== "string" || !urlOrFragment) return null;
+  let fragment = urlOrFragment;
+  const hash = urlOrFragment.indexOf("#");
+  if (hash >= 0) {
+    fragment = urlOrFragment.slice(hash + 1);
+  }
+  const dot = fragment.indexOf(".");
+  if (dot <= 0) return null;
+  const version = fragment.slice(0, dot);
+  const payload = fragment.slice(dot + 1);
+  if (!payload) return null;
+  if (version === STATE_CODEC_VERSION) {
+    try {
+      const raw = Buffer.from(payload, "base64url");
+      const json = inflateSync(raw).toString("utf8");
+      return JSON.parse(json);
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function isStateUrl(value) {
+  if (typeof value !== "string" || !value) return false;
+  if (value.startsWith(STATE_URL_PREFIX)) {
+    return decodeStateUrl(value) !== null;
+  }
+  if (value.startsWith(`${STATE_CODEC_VERSION}.`)) {
+    return decodeStateUrl(value) !== null;
+  }
+  return false;
+}
+
+// src/host.ts
+var STATE_ELEMENT_ID = "card_state";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function walk(node, visit, parent = null) {
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit, parent);
+    return;
+  }
+  if (!isRecord(node)) return;
+  visit(node, parent);
+  for (const value of Object.values(node)) walk(value, visit, node);
+}
+function extractStateUrl(node) {
+  const action = node.action;
+  if (isRecord(action)) {
+    const multi = action.multi_url;
+    if (isRecord(multi) && typeof multi.url === "string" && isStateUrl(multi.url)) {
+      return multi.url;
+    }
+    if (typeof action.url === "string" && isStateUrl(action.url)) {
+      return action.url;
+    }
+  }
+  if (Array.isArray(node.actions)) {
+    for (const item of node.actions) {
+      if (!isRecord(item)) continue;
+      const inner = isRecord(item.action) ? item.action : item;
+      for (const key of ["url", "default_url", "pc_url", "ios_url", "android_url", "pcURL", "iosURL", "androidURL"]) {
+        const v = inner[key];
+        if (typeof v === "string" && isStateUrl(v)) return v;
+      }
+    }
+  }
+  const property = node.property;
+  if (isRecord(property) && Array.isArray(property.actions)) {
+    for (const item of property.actions) {
+      if (!isRecord(item)) continue;
+      const inner = isRecord(item.action) ? item.action : item;
+      for (const key of ["url", "pcURL", "iosURL", "androidURL"]) {
+        const v = inner[key];
+        if (typeof v === "string" && isStateUrl(v)) return v;
+      }
+    }
+  }
+  if (isRecord(node.multi_url) && typeof node.multi_url.url === "string" && isStateUrl(node.multi_url.url)) {
+    return node.multi_url.url;
+  }
+  return null;
+}
+function isStateHost(node) {
+  if (node.tag === "column_set" && node.element_id === STATE_ELEMENT_ID) return true;
+  if (node.tag === "column_set" && node.id === STATE_ELEMENT_ID) return true;
+  if (node.tag === "column_set" && extractStateUrl(node)) return true;
+  if (node.id === STATE_ELEMENT_ID && extractStateUrl(node)) return true;
+  return false;
+}
+function createStateHost(stateUrl) {
+  return {
+    tag: "column_set",
+    element_id: STATE_ELEMENT_ID,
+    action: {
+      multi_url: {
+        url: stateUrl
+      }
+    },
+    columns: [
+      {
+        tag: "column",
+        width: "auto",
+        elements: []
+      }
+    ]
+  };
+}
+function ensureBodyElements(card) {
+  const existing = card.body;
+  const body = isRecord(existing) ? existing : { elements: [] };
+  if (!isRecord(existing)) {
+    card.body = body;
+  }
+  if (!Array.isArray(body.elements)) {
+    body.elements = [];
+  }
+  return body.elements;
+}
+function findStateHost(card) {
+  let found = null;
+  walk(card, (obj) => {
+    if (found) return;
+    if (isStateHost(obj)) found = obj;
+  });
+  return found;
+}
+function readCardState(card) {
+  const host = findStateHost(card);
+  if (host) {
+    const url = extractStateUrl(host);
+    if (url) {
+      const state = decodeStateUrl(url);
+      return state;
+    }
+  }
+  let decoded = null;
+  walk(card, (obj) => {
+    if (decoded !== null) return;
+    const url = extractStateUrl(obj);
+    if (url) decoded = decodeStateUrl(url);
+  });
+  if (decoded === null) {
+    walk(card, (obj) => {
+      if (decoded !== null) return;
+      for (const v of Object.values(obj)) {
+        if (typeof v === "string" && v.startsWith(STATE_URL_PREFIX)) {
+          const s = decodeStateUrl(v);
+          if (s !== null) {
+            decoded = s;
+            return;
+          }
+        }
+      }
+    });
+  }
+  return decoded;
+}
+function sealCardState(card, state) {
+  const stateUrl = encodeStateUrl(state);
+  const elements = ensureBodyElements(card);
+  const next = elements.filter((el) => !(isRecord(el) && isStateHost(el)));
+  next.push(createStateHost(stateUrl));
+  const body = card.body;
+  body.elements = next;
+  return stateUrl;
+}
+function unsealCardState(card) {
+  const state = readCardState(card);
+  const body = isRecord(card.body) ? card.body : null;
+  if (body && Array.isArray(body.elements)) {
+    body.elements = body.elements.filter((el) => !(isRecord(el) && isStateHost(el)));
+  }
+  return state;
+}
+
+export { STATE_CODEC_VERSION, STATE_ELEMENT_ID, STATE_URL_BASE, STATE_URL_PREFIX, StateCodecError, createStateHost, decodeStateUrl, encodeStateUrl, findStateHost, isStateUrl, readCardState, sealCardState, unsealCardState };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@open-feishu-card/store",
+  "version": "0.1.0",
+  "description": "把卡片运行时 state 封印进空分栏 action.multi_url（deflate + base64url），支持 DSL / RAW 回读",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.3",
+    "typescript": "^7.0.2"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ztxtxwd/open-feishu-card-monorepo.git",
+    "directory": "packages/store"
+  }
+}