@goflowstate/widget-sdk

中文文档
0.3.5发布于 2026/11/15MITTypeScriptES Module近 30 天下载 1万

SDK for building Flowstate Canvas widgets

原始使用文档
文档目录13 节
  1. Installation
  2. Quick Start
  3. ESM (bundler / TypeScript)
  4. Script tag (no bundler)
  5. Emitting and Subscribing to Events
  6. Persistent Storage
  7. AI Completions
  8. User Context and Consent
  9. Notifications
  10. Viewer claims (shell guests)
  11. Flow feedback (the bug icon)
  12. Full API Reference
  13. License

@goflowstate/widget-sdk

SDK for building widgets that run inside the Flowstate Canvas.

Installation

npm install @goflowstate/widget-sdk

Or via CDN (no bundler required):

<script src="https://unpkg.com/@goflowstate/widget-sdk/dist/canvas-widget-sdk.js"></script>

Quick Start

ESM (bundler / TypeScript)

import { CanvasWidget } from '@goflowstate/widget-sdk';

const widget = await CanvasWidget.init();

// React to display state changes
widget.onStateChange((state) => {
  console.log('Widget state:', state); // 'collapsed' | 'expanding' | 'expanded' | 'collapsing'
});

// Expand into modal view
document.getElementById('open-btn')?.addEventListener('click', () => {
  widget.requestExpand();
});

Script tag (no bundler)

<script src="canvas-widget-sdk.js"></script>
<script>
  CanvasWidget.init().then((widget) => {
    widget.onStateChange((state) => console.log(state));
  });
</script>

Emitting and Subscribing to Events

const widget = await CanvasWidget.init();

// Broadcast to other widgets on the same canvas
widget.emit('timer:tick', { remaining: 60 });

// Listen for events from other widgets
const unsub = widget.subscribe('timer:tick', (event) => {
  console.log(event.topic, event.payload);
});

// Stop listening
unsub();

Persistent Storage

const widget = await CanvasWidget.init();

// Store a value (scoped to this widget installation)
await widget.storage.set('count', 42);

// Retrieve a value
const count = await widget.storage.get('count');

// Remove a value
await widget.storage.delete('count');

AI Completions

Call the platform's models without holding any provider key. Every call is metered and attributed to your publishing org.

const widget = await CanvasWidget.init();

// One-shot completion
const res = await widget.ai.complete({
  alias: 'widget.gpt-mini', // widget.* aliases only — never raw model ids
  system: 'You summarise kanban boards in one sentence.',
  messages: [{ role: 'user', content: boardAsText }],
});
console.log(res.text, res.inputTokens, res.outputTokens);

// Streaming
for await (const ev of widget.ai.stream({
  alias: 'widget.haiku',
  messages: [{ role: 'user', content: 'Brainstorm three icebreakers.' }],
})) {
  if (ev.type === 'text') appendToUi(ev.text);
  if (ev.type === 'done') console.log('tokens:', ev.inputTokens, ev.outputTokens);
  if (ev.type === 'error') showError(ev.message);
}

Available aliases: widget.haiku (Anthropic, fast), widget.sonnet (Anthropic, strongest), widget.gpt (OpenAI, strongest), widget.gpt-mini (OpenAI, fast), widget.gemini (Google, strongest), widget.gemini-mini (Google, fast), widget.sonar (Perplexity, answers grounded in live web search), widget.sonar-pro (Perplexity, web-grounded, deeper research). Aliases are platform-managed; the model behind one can improve without a code change on your side.

Notes:

  • maxTokens is clamped server-side to [256, 4096] (default 1024). The floor exists because the OpenAI aliases are reasoning models: a tiny budget gets consumed entirely by invisible reasoning and returns empty text with stopReason: 'length'. If you see empty text, raise the budget.
  • Breaking out of a stream() loop cancels the upstream call, so you are not billed for text you stopped reading.
  • Budget errors surface with messages starting usage limit reached — catch them to show your own copy.
const widget = await CanvasWidget.init();

// Request access to user data
const result = await widget.requestConsent('user:profile', 'Needed to personalise your experience');
if (result.granted) {
  console.log('User:', widget.user?.displayName);
}

Notifications

widget.notify('Saved!', { level: 'info', duration: 3000 });

Viewer claims (shell guests)

A session opened from a unishell shell page belongs to a guest whose name, email or phone the shell has already verified. Those facts arrive on every state read as state.viewer.claims, and the latest ones are on session.claims:

const session = CanvasWidget.initSession();
const state = await session.join();
const email = session.claims?.email; // { type, value, source, verifiedAt? } | undefined

Claims are only ever the reader's own, and they are context, not authorization. session.claims is null for members, for PWA guests and before the first state arrives.

Flow feedback (the bug icon)

A flow that calls CanvasWidget.initSession() carries the feedback icon with no code of its own. While the ring has feedback switched on, the session state says so and the SDK puts a round button in the corner of the page. A tap opens a sheet with one field at once and takes a screenshot of the page behind it, and neither the icon nor the sheet is in it. The sheet says each step: corner marks frame the page and the slot reads "Taking a screenshot" (up to 15 seconds), then "Screenshot attached" with the picture and a check, or "No screenshot" with "Take screenshot" when it could not be taken or was removed. The button reads "Sending" while the note goes out, and the sheet ends on "Feedback sent" before it closes. The note is sent through the flow's session to POST /api/w/:slug/feedback.

The icon and the sheet take the look of the page they sit on: its fonts, ground, ink, the fill and shape of its main button, and its corner radius. To pin a role, set a custom property on :root:

:root {
  --fs-feedback-cta: #5136c4; /* also -cta-ink, -ground, -ink, -font, -font-display, -radius */
  --fs-feedback-bottom: 96px; /* where the icon sits; also -right */
}

The sheet's type comes from the words the flow is drawing, not from <body>: the title takes the face, weight and letter spacing of the flow's largest heading, the note and the field take the face most of the flow's smaller text is set in, and the send button takes the face, weight, letter spacing and case of the flow's main button. Pin --fs-feedback-font or --fs-feedback-font-display when the reading is off.

The button floats over the flow and belongs to the person using it. They can drag it anywhere, and it settles on the nearer side. A flick at an edge, or a drag into one, docks it there as a slim tab with the bug still showing; a tap on the tab opens the sheet, and pulling the tab inward floats it again. The sheet also has a "Tuck the button to the side" link. Where a person leaves the button is remembered.

Until a person moves it, the button keeps clear of the page's own controls. It starts in the bottom corner and, whenever the page changes, resizes or stops scrolling, looks up the right edge for the lowest spot that is empty. It sits over a line of text only when empty space is far above it, and on a control only when the whole edge is controls. Pinning --fs-feedback-bottom turns that off and holds the icon where the flow puts it.

To take the icon off one screen of a flow (a film, a full-screen picture), set --fs-feedback-display: none from the flow's stylesheet while that screen is up, for example :root:has(.film) { --fs-feedback-display: none; }.

Name each screen so a report says where it came from: document.body.dataset.pageKey = 'question-2'. A page that must not show the icon (a projected wall) sets <html data-fs-feedback="off">.

Full API Reference

See the Flowstate developer docs for the complete API reference, the manifest format, the AI integration guide, and the submission pipeline.

License

MIT

版本与发布记录

@goflowstate/widget-sdk 共发布 10 个版本,首次发布于 2026/07/07;过去 12 个月发布了 10 个版本。

版本发布日期距今
0.3.5latest2026/11/151 天前
0.3.42026/11/152 天前
0.3.22026/11/115 天前
0.3.12026/11/115 天前
0.3.02026/10/2819 天前
0.2.22026/08/232 个月前

关于 @goflowstate/widget-sdk 的常见问题

@goflowstate/widget-sdk 是什么?

SDK for building Flowstate Canvas widgets

如何安装 @goflowstate/widget-sdk?

在项目目录运行 npm install @goflowstate/widget-sdk,或使用 pnpm add / yarn add / bun add。

@goflowstate/widget-sdk 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@goflowstate/widget-sdk 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@goflowstate/widget-sdk 可以商用吗?

@goflowstate/widget-sdk 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@goflowstate/widget-sdk 的下载量有多少?

根据 npm 官方下载统计,@goflowstate/widget-sdk 在 2026/10/17 – 2026/11/15 这 30 天内被下载 10,363 次,日均约 345 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@goflowstate/widget-sdk 还在维护吗?

最新版本 0.3.5 发布于 2026/11/15(1 天前);至今共发布 10 个版本,其中过去 12 个月发布了 10 个;首次发布于 2026/07/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。