@viceme-ai/sdk 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @viceme-ai/sdk
 
-PUBLIC-only ViceMe browser SDK for the Shop-hosted danmaku overlay.
+ViceMe browser SDK for Shop-hosted engagement and origin-bound Website Work access.
 
 ## Install
 
@@ -11,23 +11,26 @@ pnpm add @viceme-ai/sdk
 ## 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"
-  data-viceme-target="body"
+  data-viceme-features="danmaku,tip"
+  data-viceme-target="#viceme-engagement"
   data-viceme-theme="auto"
 ></script>
 ```
 
-The feature declaration must be exactly `danmaku`.
+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 entry, 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.
+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'`
@@ -39,30 +42,56 @@ exact origin. Do not use `*` or a ViceMe subdomain wildcard.
 ```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();
 
-const mounted = await mountDanmaku(client, {
-  target: document.body,
-  theme: 'auto',
-});
+const target = document.querySelector('#viceme-engagement');
+if (!target) throw new Error('ViceMe target missing');
 
-mounted.destroy();
+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();
 ```
 
 Run those cleanup calls from the owning component's unmount path or another
 explicit lifecycle boundary, not from `pagehide` (which also covers bfcache).
 
-`createViceMe` is purely local and never contacts Shop. A live client reports
-only the `danmaku` capability. The hosted `/embed/danmaku` iframe uses Shop's
+`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`.
+`/v1/danmaku/messages`. The `/widget/tip/<workKey>` iframe handles login and
+payment only after its exact parent Origin is registered.
+
+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
+const decisions = await client.access.checkMany(['members', 'pro-tools']);
+if (!decisions['pro-tools']?.allowed) {
+  await client.access.require('pro-tools');
+}
+```
 
-There is no public SDK Session, Bearer token, auth, follow, access, purchase,
-or checkout surface, and no `@viceme-ai/sdk/testing` subpath.
+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"}