@viceme-ai/sdk 0.3.0 → 0.6.1

package/README.md

@@ -1,8 +1,12 @@
 # @viceme-ai/sdk
 
-Public ViceMe browser SDK: headless core, public session, and capability
-subpaths for static HTML, browser-native ESM, React/Next.js, and
-Agent-generated sites.
+ViceMe browser SDK for Shop-hosted engagement and origin-bound Website Work access.
+
+The release PR atomically owns the package version, runtime manifest, and
+changelog update. During the current preview stage, publication does not
+require a repository license file. The root `LICENSE-PENDING.md` records the
+deferred decision without blocking release; licensing will be finalized
+separately.
 
 ## Install
 
@@ -10,63 +14,173 @@ Agent-generated sites.
 pnpm add @viceme-ai/sdk
 ```
 
-## Usage
+## Static HTML
+
+```html
+<div id="viceme-engagement"></div>
+<script
+  defer
+  src="https://s3.viceme.cn/viceme-sdk/0.5.0/viceme.min.js"
+  data-viceme-work="wrk_live_demo"
+  data-viceme-region="cn"
+  data-viceme-features="danmaku,tip"
+  data-viceme-target="#viceme-engagement"
+  data-viceme-theme="auto"
+></script>
+```
+
+The feature declaration accepts `danmaku`, `tip`, or both without whitespace or
+duplicates.
+
+Static CDN entry points always use an immutable exact-version directory. The CN
+host is `s3.viceme.cn`; GLOBAL uses `s3.viceme.ai`. The `0.5.0` URL above is the
+current source target and is unavailable until that exact release is published
+and verified.
+
+With CSP, allow the exact regional S3 origin in `script-src` and `connect-src`,
+the exact regional Shop origin in `frame-src`, and keep `object-src 'none'`. A
+nonce with `'strict-dynamic'` may authorize dynamic scripts, but the other
+directives still need exact origins. Do not use `*` or a ViceMe subdomain
+wildcard.
+
+## ESM
 
 ```ts
 import { createViceMe } from '@viceme-ai/sdk';
+import { mountDanmaku } from '@viceme-ai/sdk/danmaku';
+import { mountTip } from '@viceme-ai/sdk/tip';
 
-const client = createViceMe({ workKey: 'wrk_public_xxx', region: 'cn' });
+const client = createViceMe({ workKey: 'wrk_live_demo', region: 'cn' });
 await client.ready();
 
-// Use server-authoritative titles and prices in the host site's existing
-// Button/Card components. This does not open or customize ViceMe checkout.
-const features = await client.access.getFeatures();
-const emperor = features.find((feature) => feature.featureKey === 'emperor');
-
-const access = await client.access.checkMany(['dingdong', 'emperor']);
-if (access.dingdong.allowed) enableDingdong();
-if (access.emperor.allowed) enableEmperor();
+const target = document.querySelector('#viceme-engagement');
+if (!target) throw new Error('ViceMe target missing');
 
-// Call from a user gesture. A denied decision opens the ViceMe
-// bottom-sheet/in-page Web Component. Creator details and recent work covers appear
-// above one authorization action; accepted authorization automatically follows.
-const decision = await client.access.require('emperor');
-if (decision.allowed) enableEmperor();
+const results = await Promise.allSettled([
+  mountDanmaku(client, { target, theme: 'auto' }),
+  mountTip(client, { target, theme: 'auto' }),
+]);
+const mounted = results.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
 
+mounted.forEach((handle) => handle.destroy());
 client.destroy();
 ```
 
-When adding a host-side locked state or purchase entry, preserve the site's
-existing component library, design tokens, responsive behavior, and feedback
-patterns. Keep the original business action unchanged and call it only after
-`access.require()` returns an allowed decision. Never hard-code a price from
-local configuration; `getFeatures()` returns the current display price. The
-ViceMe-owned authorization and checkout layer remains isolated and unchanged.
+Run those cleanup calls from the owning component's unmount path or another
+explicit lifecycle boundary, not from `pagehide` (which also covers bfcache).
+
+`createViceMe` and `ready()` are purely local and never contact Shop. A live client reports
+build support for `danmaku` and `tip`; Shop remains authoritative for whether a
+Work enables either capability. The hosted `/embed/danmaku` iframe uses Shop's
+internal SDK to read and create anonymous messages through
+`/v1/danmaku/messages`. The `/widget/tip/<workKey>` iframe owns confirmation,
+payment, risk, and result authority. Visitors do not sign in to ViceMe and are
+anonymous to the creator; the observed parent Origin is attribution rather than
+an authorization gate.
+
+Pass a selected public pair value: `keys.test` is `wrk_test_...` and `keys.live`
+is `wrk_live_...`. Other Work key shapes are rejected locally.
+
+Access operations establish a short-lived, memory-only Work session on first
+use. They expose `client.auth`, `client.access`, and `client.checkout`; login,
+explicit follow, and hosted checkout remain ViceMe-owned UI. The host never
+receives a general ViceMe session or payment credential. Tests can inject a
+deterministic transport and presenter through `@viceme-ai/sdk/testing`.
+
+Website access login renders the work-bound WeChat QR code directly in the SDK
+layer. Paid access keeps desktop QR payment and WeChat JSAPI in that layer;
+mobile H5/WAP payment may open a provider page or app. The original page polls
+the server-authoritative access decision and closes the layer after entitlement
+is active. This behavior does not change the separate Tip Widget flow.
 
-The SDK registers and mounts `<viceme-access-layer>` with isolated ViceMe-owned
-styles. Authorization and checkout remain inside its iframe area and complete through
-an origin- and channel-validated message; no browser popup, page navigation,
-`confirm`, or `alert` is used. Custom site presenters and style inference are
-not part of the current public contract. WeChat opens directly inside the frame,
-and the checkout frame keeps a stable height while its content loads.
+```ts
+const decisions = await client.access.checkMany(['members', 'pro-tools']);
+if (!decisions['pro-tools']?.allowed) {
+  await client.access.require('pro-tools');
+}
+```
+
+The Tip subpath exports `TipPaidDetail` and `TipWidgetCloseDetail` for the
+sanitized `viceme:tip-paid` and `viceme:widget-close` `CustomEvent` details.
+`TipPaidDetail` contains only `status`, trusted `work.id/title`, amount, and CNY;
+it contains no key, provider, order number, token, or transaction identifier.
 
-Static HTML sites can use the CDN auto-loader instead — see the
-[repository README](https://github.com/ViceMe-AI/sdk).
+The danmaku mount hashes the canonical page URL locally, combines it with a 10%
+scroll bucket, and sends only the opaque anchor to the hosted iframe. Destroying
+the mount removes its nodes, listeners, debounce timer, and location poll.
 
-## Testing your integration
+The Tip mount sends no amount, provider, token, or application ID. It enables
+interaction only after a trusted resize handshake. Shop resets its hosted
+payment surface on Escape before sending close; the SDK forwards sanitized
+close and paid notifications, and removes its iframe, timer, media listener,
+and message listener on destroy.
+
+## Headless Tip
+
+This additive API targets `0.5.0`. Do not expect `createTip` or
+`@viceme-ai/sdk/tip/testing` from the immutable npm `0.4.0` package.
 
 ```ts
-import { createTestViceMe, createMemoryTransport } from '@viceme-ai/sdk/testing';
-
-const client = createTestViceMe({
-  workKey: 'wrk_test',
-  region: 'cn',
-  transport: createMemoryTransport({
-    work: { key: 'wrk_test', capabilities: ['fixture'] },
-  }),
+import { createViceMe } from '@viceme-ai/sdk';
+import { createTip } from '@viceme-ai/sdk/tip';
+
+const client = createViceMe({ workKey: 'wrk_live_demo', region: 'cn' });
+const tip = createTip(client);
+const config = await tip.getConfig();
+
+button.addEventListener('click', async () => {
+  const result = await tip.open({
+    amountCents: config.amount.minCents,
+    provider: config.providers[0],
+    locale: 'zh-CN',
+    appearance: 'auto',
+  });
+  console.log(result.status);
 });
-await client.ready();
+
+function destroyTip() {
+  tip.destroy();
+  client.destroy();
+}
+```
+
+Call `destroyTip()` from the owning component or route cleanup. Do not bind it
+to `pagehide`, because that event also fires when a page enters the bfcache.
+
+`getConfig()` strictly parses the credential-free regional
+`GET /v1/work-sdk/<encoded-workKey>/tip-config` response. Call `open()` directly
+from user activation so it can create its secure full-screen frame in the same
+call stack. Only `PAID`, `CANCELLED`, and `UNKNOWN` cross back; no order number,
+token, payment action, or transaction ID is exposed. `scene`, `metadata`, and
+`testMode` are rejected or absent from the API.
+
+The config `environment` remains server-authoritative. The SDK checks only that
+`wrk_test_...` is paired with `SANDBOX` and `wrk_live_...` with `PRODUCTION`, and
+rejects inconsistent responses.
+
+The first Tip release is CN/CNY only. `region: 'global'` fails locally with
+`CAPABILITY_DISABLED` without a config request or iframe. Anonymous Tip does not
+use the legacy WeChat JSAPI user/OpenID path.
+
+`TIP_CONFIG_INVALID` is a non-retryable Shop/SDK contract mismatch and should be
+reported rather than retried. `TIP_OPEN_IN_PROGRESS` means the existing call
+must settle first. `TIP_READY_TIMEOUT` is retryable after the failed call has
+cleaned itself up. On every component or route unmount, call `tip.destroy()`
+before `client.destroy()` so an in-flight flow settles as `UNKNOWN` and leaves
+no portal or message listener behind.
+
+Immutable exact-version CDN ESM exports the same implementation from
+`<origin>/viceme-sdk/<version>/index.js` and `tip.js` without adding a `window`
+global.
+
+Use the scoped fake in components and Storybook:
+
+```ts
+import { createTestTip } from '@viceme-ai/sdk/tip/testing';
+
+const paid = createTestTip({ config, outcome: 'PAID' });
+const failed = createTestTip({ config, outcome: new Error('fixture failure') });
 ```
 
-Consumers branch on stable `ViceMeError.code` values only — never on error
-messages. Work-session tokens and work-scoped users remain in memory only.
+The config may also be an `Error`. `SANDBOX` is always supplied by server config
+for a test Work, never by a production SDK switch.

package/dist/browser-events.d.ts

@@ -0,0 +1,52 @@
+/** Stable, allowlisted `viceme:*` DOM events shared by hosted capabilities. */
+import type { ViceMeErrorCode } from './core/errors.ts';
+export interface VicemeReadyDetail {
+    clientKey: string;
+    workKey: string;
+    capabilities: string[];
+    version: string;
+}
+export interface VicemeCapabilityReadyDetail {
+    clientKey: string;
+    instanceKey: string;
+    capability: string;
+    version: string;
+}
+export interface VicemeErrorDetail {
+    clientKey?: string;
+    instanceKey?: string;
+    capability?: string;
+    code: ViceMeErrorCode;
+    retryable: boolean;
+    requestId?: string;
+}
+export interface VicemeDestroyedDetail {
+    clientKey: string;
+    instanceKey: string;
+    capability: string;
+}
+export interface VicemeWidgetCloseDetail {
+    workId: string;
+}
+export interface VicemeTipPaidDetail {
+    status: 'PAID';
+    work: {
+        id: string;
+        title: string;
+    };
+    amountCents: number;
+    currency: 'CNY';
+}
+export type VicemeEventType = 'viceme:ready' | 'viceme:capability-ready' | 'viceme:error' | 'viceme:destroyed' | 'viceme:widget-close' | 'viceme:tip-paid';
+export type VicemeEventDetailMap = {
+    'viceme:ready': VicemeReadyDetail;
+    'viceme:capability-ready': VicemeCapabilityReadyDetail;
+    'viceme:error': VicemeErrorDetail;
+    'viceme:destroyed': VicemeDestroyedDetail;
+    'viceme:widget-close': VicemeWidgetCloseDetail;
+    'viceme:tip-paid': VicemeTipPaidDetail;
+};
+/** Strip anything outside the documented allowlist before dispatch. */
+export declare function sanitizeDetail(type: VicemeEventType, detail: VicemeEventDetailMap[VicemeEventType]): VicemeEventDetailMap[VicemeEventType];
+export declare function dispatchViceMeEvent<K extends VicemeEventType>(target: EventTarget, type: K, detail: VicemeEventDetailMap[K]): void;
+//# sourceMappingURL=browser-events.d.ts.map

package/dist/browser-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-events.d.ts","sourceRoot":"","sources":["../src/browser-events.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,yBAAyB,GACzB,cAAc,GACd,kBAAkB,GAClB,qBAAqB,GACrB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,EAAE,iBAAiB,CAAC;IAClC,yBAAyB,EAAE,2BAA2B,CAAC;IACvD,cAAc,EAAE,iBAAiB,CAAC;IAClC,kBAAkB,EAAE,qBAAqB,CAAC;IAC1C,qBAAqB,EAAE,uBAAuB,CAAC;IAC/C,iBAAiB,EAAE,mBAAmB,CAAC;CACxC,CAAC;AAcF,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,eAAe,EACrB,MAAM,EAAE,oBAAoB,CAAC,eAAe,CAAC,GAC5C,oBAAoB,CAAC,eAAe,CAAC,CAgBvC;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,eAAe,EAC3D,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAQN"}

package/dist/capability-mount.d.ts

@@ -0,0 +1,15 @@
+import type { ViceMeClient } from './core/client.ts';
+export interface CapabilityMountOptions {
+    /** Mount host element; the capability owns its Shadow DOM subtree. */
+    target: Element;
+    theme: 'light' | 'dark' | 'auto';
+    /** Abort a mount that has not completed and destroy it after completion. */
+    signal?: AbortSignal;
+}
+/** A capability's own lifecycle handle; the loader assigns public identity. */
+export interface CapabilityMountHandle {
+    readonly capability: string;
+    destroy(): void;
+}
+export type CapabilityMountFunction = (client: ViceMeClient, options: CapabilityMountOptions) => Promise<CapabilityMountHandle>;
+//# sourceMappingURL=capability-mount.d.ts.map

package/dist/capability-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-mount.d.ts","sourceRoot":"","sources":["../src/capability-mount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,sBAAsB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC"}

package/dist/chunks/build-endpoints-NrDmg6jf.js

@@ -0,0 +1,12 @@
+const t = {
+  cn: "https://api.viceme.cn",
+  global: "https://api.viceme.ai"
+}, c = {
+  cn: "https://viceme.cn",
+  global: "https://viceme.ai"
+};
+export {
+  c as B,
+  t as a
+};
+//# sourceMappingURL=build-endpoints-NrDmg6jf.js.map

package/dist/chunks/build-endpoints-NrDmg6jf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-endpoints-NrDmg6jf.js","sources":["../../src/core/build-endpoints.ts"],"sourcesContent":["declare const __VICEME_BUILD_CN_API_BASE_URL__: string | undefined;\ndeclare const __VICEME_BUILD_GLOBAL_API_BASE_URL__: string | undefined;\ndeclare const __VICEME_BUILD_CN_WIDGET_ORIGIN__: string | undefined;\ndeclare const __VICEME_BUILD_GLOBAL_WIDGET_ORIGIN__: string | undefined;\n\n/** Public Shop API origins baked into immutable release artifacts. */\nexport const BUILD_API_BASE_URLS = {\n  cn:\n    typeof __VICEME_BUILD_CN_API_BASE_URL__ === 'string'\n      ? __VICEME_BUILD_CN_API_BASE_URL__\n      : 'https://api.viceme.cn',\n  global:\n    typeof __VICEME_BUILD_GLOBAL_API_BASE_URL__ === 'string'\n      ? __VICEME_BUILD_GLOBAL_API_BASE_URL__\n      : 'https://api.viceme.ai',\n} as const;\n\n/** Hosted Shop origins baked into immutable release artifacts. */\nexport const BUILD_WIDGET_ORIGINS = {\n  cn:\n    typeof __VICEME_BUILD_CN_WIDGET_ORIGIN__ === 'string'\n      ? __VICEME_BUILD_CN_WIDGET_ORIGIN__\n      : 'https://viceme.cn',\n  global:\n    typeof __VICEME_BUILD_GLOBAL_WIDGET_ORIGIN__ === 'string'\n      ? __VICEME_BUILD_GLOBAL_WIDGET_ORIGIN__\n      : 'https://viceme.ai',\n} as const;\n"],"names":["BUILD_API_BASE_URLS","BUILD_WIDGET_ORIGINS"],"mappings":"AAMO,MAAMA,IAAsB;AAAA,EACjC,IAEM;AAAA,EAEN,QAEM;AAER,GAGaC,IAAuB;AAAA,EAClC,IAEM;AAAA,EAEN,QAEM;AAER;"}