@viceme-ai/sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,6 @@
 # @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.
 
 ## Install
 
@@ -10,63 +8,90 @@ Agent-generated sites.
 pnpm add @viceme-ai/sdk
 ```
 
-## Usage
+## Static HTML
+
+```html
+<div id="viceme-engagement"></div>
+<script
+  defer
+  src="https://viceme.cn/viceme-sdk/v1/viceme.min.js"
+  data-viceme-work="wrk_public_xxx"
+  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.
+
+The `viceme.cn/viceme-sdk/v1/*` Shop proxy directly exposes one configured
+exact release, including the loader, manifest, danmaku and Tip entries, and
+hashed chunks. It is distinct from the direct S3 `v1/viceme.min.js` alias,
+whose fixed bootstrap reads `-/aliases/v1` before loading an exact-version
+directory.
+
+With CSP, allow the exact regional Shop origin in `script-src`, `connect-src`,
+and `frame-src`, and keep `object-src 'none'`. A nonce with `'strict-dynamic'`
+may authorize dynamic scripts, but `connect-src` and `frame-src` still need the
+exact origin. 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' });
 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 target = document.querySelector('#viceme-engagement');
+if (!target) throw new Error('ViceMe target missing');
 
-const access = await client.access.checkMany(['dingdong', 'emperor']);
-if (access.dingdong.allowed) enableDingdong();
-if (access.emperor.allowed) enableEmperor();
-
-// 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.
-
-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.
+Run those cleanup calls from the owning component's unmount path or another
+explicit lifecycle boundary, not from `pagehide` (which also covers bfcache).
 
-Static HTML sites can use the CDN auto-loader instead — see the
-[repository README](https://github.com/ViceMe-AI/sdk).
+`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 handles login and
+payment only after its exact parent Origin is registered.
 
-## Testing your integration
+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. There is no public
+`@viceme-ai/sdk/testing` subpath.
 
 ```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'] },
-  }),
-});
-await client.ready();
+const decisions = await client.access.checkMany(['members', 'pro-tools']);
+if (!decisions['pro-tools']?.allowed) {
+  await client.access.require('pro-tools');
+}
 ```
 
-Consumers branch on stable `ViceMeError.code` values only — never on error
-messages. Work-session tokens and work-scoped users remain in memory only.
+The Tip subpath exports `TipPaidDetail` and `TipWidgetCloseDetail` for the
+sanitized `viceme:tip-paid` and `viceme:widget-close` `CustomEvent` details.
+
+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.
+
+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.

package/dist/browser-events.d.ts

@@ -0,0 +1,49 @@
+/** 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 {
+    workId: string;
+    orderNo: string;
+    status: 'PAID';
+    amountCents: number;
+}
+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,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;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,CAOvC;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"}