@jixo/opendweb-client-sdk 0.1.0 → 0.2.0

package/index.d.ts

@@ -1,9 +1,30 @@
-export interface FabricEventJs {
-  type: 'peer-connected' | 'peer-disconnected' | 'roster-updated' | 'message' | 'path-changed'
-  endpointId?: string
-  from?: string
-  data?: Buffer
-  status?: 'direct' | 'relay' | 'unknown'
+/** 事件判别联合：relay-* 事件必携带完整快照 payload（非可选） */
+/** 代理策略：none=直连；from-env=读环境代理；url 形态仅 SDK 使用 */
+export type HttpProxyOptions = 'none' | 'from-env' | { url: string }
+
+/** 从 SDK 错误消息的 [<kebab-code>] 前缀派生稳定错误码（SCREAMING_SNAKE）；无前缀返回 null */
+export declare function deriveErrorCode(message: string): string | null
+
+export type FabricEventJs =
+  | {
+      type: 'peer-connected' | 'peer-disconnected'
+      endpointId: string
+    }
+  | { type: 'roster-updated' }
+  | { type: 'message'; from: string; data: Buffer }
+  | { type: 'path-changed'; endpointId: string; status: 'direct' | 'relay' | 'unknown' }
+  | { type: 'relay-online' | 'relay-offline'; relay: RelayStatusJs }
+
+/** relay 状态快照（relayStatus() 返回值与 relay-* 事件 payload 同构） */
+export interface RelayStatusJs {
+  /** 字面量联合（非 string） */
+  mode: 'disabled' | 'custom' | 'n0'
+  /** 配置的 relay URL 列表（disabled 为空数组；n0 恒为 ["https://relay.iroh.network"]） */
+  urls: string[]
+  /** null <=> mode === "disabled"；否则为任一 relay 已连接 */
+  online: boolean | null
+  /** 最近一次连接错误类别（脱敏：无凭证段；无错误为 null） */
+  lastError: string | null
 }
 
 /* auto-generated by NAPI-RS */
@@ -19,7 +40,11 @@ export declare class Fabric {
   static open(opts: FabricOptions, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
   /** 以加入者身份起步（空名册；随后调用 join 兑换邀请）。 */
   static attach(opts: FabricOptions, fabricIdHex: string, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
-  /** 一步加入：从令牌解析 fabric_id，attach + 兑换 + 持久化名册。 */
+  /**
+   *  一步加入：从令牌解析 fabric_id，attach + 兑换 + 持久化名册。
+   *  令牌前置检查（解码/过期/地址规范化）先于本地数据面加载与身份句柄消费
+   * （D11 冻结顺序：令牌自身错误优先于目录检查）。
+   */
   static joinWithToken(opts: FabricOptions, token: string, secret?: SecretSeedHandle | undefined | null): Promise<Fabric>
   /** 本节点 EndpointId（z-base-32，52 字符） */
   get endpointId(): string
@@ -29,8 +54,12 @@ export declare class Fabric {
   members(): Promise<Array<Member>>
   /** 查询 EndpointId 是否为有效成员 */
   isMember(endpointId: string): Promise<boolean>
-  /** 签发邀请令牌（root-only）。返回 dweb1. 前缀的自包含字符串。 */
-  invite(ttlMs: number, recipient?: string | undefined | null): Promise<string>
+  /**
+   * 签发邀请令牌（root-only）。返回 dweb1. 前缀的自包含字符串。
+   * 第三参 opts 透传签发安全门逃生阀：relay 为空且 advertiseAddrs 为空时，
+   * 无 opts 或 allowRelayless !== true => reject（[invite-without-relay]）。
+   */
+  invite(ttlMs: number, recipient?: string | undefined | null, opts?: InviteOptions | undefined | null): Promise<string>
   /** 兑换邀请令牌加入 fabric（issuer-online 单次兑换）。 */
   join(token: string): Promise<void>
   /** 连接成员（常规通道；双向门控 + 名册同步）。幂等（活跃连接直接成功）。 */
@@ -45,6 +74,11 @@ export declare class Fabric {
   setDisplayName(name: string): Promise<void>
   /** 查询与某成员的当前路径类型："direct" | "relay" | "unknown" */
   linkStatus(endpointId: string): Promise<string>
+  /**
+   * relay 状态快照（零等待，读内核缓存）。快照优先于事件：初始事实一律先查
+   * 本方法，事件只承载后续跳变。禁用模式 online 为 null（而非 false）。
+   */
+  relayStatus(): Promise<RelayStatusJs>
   /**
    * 显式导出身份（identity export，不含 roster）为 `dwebkey1.` 加密串。
    * 交由产品自行安全保存（如账号系统加密托管——密文上云、口令在用户）。
@@ -52,9 +86,11 @@ export declare class Fabric {
   exportSecretPassphrase(passphrase: string): Promise<string>
   /**
    * 注册事件回调（可多次调用，多个回调都会收到全部事件）。
-   * 事件对象见 FabricEventJs：{ type, endpointId?, from?, data?, status? }
+   * 返回句柄 id；off(id) 注销（index.js 包装为取消订阅函数）。
    */
-  on(callback: (event: FabricEventJs) => void): void
+  on(callback: (event: FabricEventJs) => void): () => void
+  /** 注销事件回调（on 返回的 id）。 */
+  off(id: number): void
   /** 优雅关闭：断开全部会话并释放网络资源。幂等。 */
   shutdown(): Promise<void>
 }
@@ -77,8 +113,20 @@ export interface FabricOptions {
   /** 数据目录（名册持久化位置；secret 默认实现也指向此目录） */
   dataDir: string
   relay?: RelayOptions
-  /** 写入邀请令牌的 issuer 直连地址（host:port） */
+  /** 写入邀请令牌的 issuer 直连地址（host:port；逐项校验，非法构造 reject） */
   advertiseAddrs?: Array<string>
+  /**
+   * HTTP 控制面（relay 连接）代理所有权；缺省 "none"。
+   * iroh endpoint 不读进程环境变量；QUIC 数据面永不经代理。
+   */
+  httpProxy?: 'none' | 'from-env' | { url: string }
+  /** join 总时限（毫秒）；缺省 30000；值域 [1000, 600000]，越界构造 reject */
+  joinTimeoutMs?: number
+}
+
+/** httpProxy 的 `{ url }` 形态（"none" | "from-env" 为字符串形态）。 */
+export interface HttpProxyUrl {
+  url: string
 }
 
 /**
@@ -87,6 +135,12 @@ export interface FabricOptions {
  */
 export declare function importSecret(token: string, passphrase: string): Promise<SecretSeedHandle>
 
+/** invite 逃生阀选项（D3）。 */
+export interface InviteOptions {
+  /** 允许签发无 relay 令牌；调用方自担可达性责任（带外路径）。 */
+  allowRelayless?: boolean
+}
+
 /** 成员信息 */
 export interface Member {
   endpointId: string
@@ -97,10 +151,8 @@ export interface Member {
 /** SDK 原生层版本 */
 export declare function nativeVersion(): string
 
-/** relay 配置 */
-export interface RelayOptions {
-  /** "disabled" | "custom" | "n0"（默认 "n0"） */
-  mode?: string
-  /** mode = "custom" 时的 relay URL 列表（自托管 docker 或其它 iroh relay） */
-  urls?: Array<string>
-}
+/** relay 配置（判别联合：非法组合构造期拒绝） */
+export type RelayOptions =
+  | { mode?: 'n0' }
+  | { mode: 'disabled' }
+  | { mode: 'custom'; urls: [string, ...string[]] }

package/index.js

@@ -46,10 +46,12 @@ function loadViaTmp() {
 
 const Native = loadViaTmp() ?? require(SRC);
 
+// on() → 取消订阅函数：原生层返回回调 id，off(id) 注销（event_callbacks 移除句柄）。
 const nativeOn = Native.Fabric.prototype.on;
+const nativeOff = Native.Fabric.prototype.off;
 Native.Fabric.prototype.on = function onWrapped(callback) {
   // 原生 TSFN 为 error-first 回调：(err, jsonString)
-  return nativeOn.call(this, (err, json) => {
+  const id = nativeOn.call(this, (err, json) => {
     if (err) return;
     const ev = JSON.parse(json);
     if (typeof ev.dataBase64 === "string") {
@@ -58,6 +60,35 @@ Native.Fabric.prototype.on = function onWrapped(callback) {
     }
     callback(ev);
   });
+  return () => nativeOff.call(this, id);
 };
 
+/**
+ * 从 SDK 错误消息的 [<kebab-code>] 前缀派生稳定错误码（SCREAMING_SNAKE）。
+ * napi Error 无自定义 code 通道——前缀约定见 contracts/error-matrix.md。
+ * 无前缀时返回 null（未分类的底层错误）。
+ */
+function deriveErrorCode(message) {
+  if (typeof message !== "string") return null;
+  const m = message.match(/^\[([a-z0-9-]+)\]\s/);
+  if (!m) return null;
+  return m[1].replace(/-/g, "_").toUpperCase();
+}
+Native.deriveErrorCode = deriveErrorCode;
+
+// relayStatus()：napi Option::None 序列化为 undefined，契约（C0 d.ts）要求 null——
+// 包装归一（事件 payload 的 relay 快照经 JSON.parse 天然是 null，无需处理）。
+const nativeRelayStatus = Native.Fabric.prototype.relayStatus;
+if (typeof nativeRelayStatus === "function") {
+  Native.Fabric.prototype.relayStatus = async function relayStatusWrapped() {
+    const r = await nativeRelayStatus.call(this);
+    return {
+      mode: r.mode,
+      urls: r.urls ?? [],
+      online: r.online ?? null,
+      lastError: r.lastError ?? null,
+    };
+  };
+}
+
 module.exports = Native;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jixo/opendweb-client-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "@jixo/opendweb-client-sdk — dweb application-level fabric SDK for Node (napi-rs binding)",
   "license": "MIT OR Apache-2.0",
   "main": "index.js",