@entmesh/sdk-miniapp 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# Entmesh Mini Program SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One privacy-first SDK for WeChat, Alipay, and Douyin mini programs. Import the runtime-specific entry, initialize before `App` and `Page` registration, grant analytics consent, and register the Collector domain in the platform console.
+
+The first public npm release is [@entmesh/sdk-miniapp@0.2.0](https://www.npmjs.com/package/@entmesh/sdk-miniapp/v/0.2.0), published on 2026-10-31. Its source is tagged [v0.2.0](https://cnb.cool/mliev/entmesh/sdk-miniapp/-/tree/v0.2.0).
+
+## Installation and platform entries
+
+Install from the public npm registry:
+
+```sh
+npm install @entmesh/sdk-miniapp --registry=https://registry.npmjs.org/
+```
+
+To reproduce the first release, install `@entmesh/sdk-miniapp@0.2.0` explicitly.
+Use the entry for your platform:
+
+| Platform | Import |
+| --- | --- |
+| WeChat | `@entmesh/sdk-miniapp/wechat` |
+| Alipay | `@entmesh/sdk-miniapp/alipay` |
+| Douyin | `@entmesh/sdk-miniapp/douyin` |
+
+Each entry exports `createClient` and the platform-independent option types.
+Import a platform subpath; the package root is not an exported entry.
+
+## Quick start
+
+```ts
+import { createClient } from '@entmesh/sdk-miniapp/wechat'
+
+const entmesh = createClient({
+  endpoint: 'https://events.example.com',
+  clientKey: 'ck_...',
+  applicationId: 'wx...',
+  consent: 'pending',
+  autocapture: true,
+})
+
+await entmesh.consent('grant')
+await entmesh.track('order_created', { order_id: 'order-1' })
+```
+
+The SDK uses platform secure-random, storage, and request APIs. It never falls back to `Math.random`, never reads host-device advertising identifiers, and never sends plaintext batches.
+
+## Page context and visible time (0.2.1)
+
+With `autocapture` enabled, the SDK tracks application startup/foreground/background
+and each page's show/hide/unload lifecycle. Initialize before `App()` and `Page()`
+registration. Page paths are recorded in `context.page.path`; manual `track()` and
+`identify()` events inherit the page that was current when the call occurred.
+`page(route, { title: 'Order details' })` also supplies `context.page.title`.
+
+Page visibility events carry `properties.visible_ms`. Each visible interval is
+counted once, even when page hiding, application backgrounding and unloading all
+occur. Background time is excluded. A page exit following an already-recorded hide
+does not repeat the duration. Startup is recorded once per SDK instance, and the
+last visibility/background events enter the persistent queue before flushing.
+
+If the user grants consent while a page is already visible, the SDK records that
+page once and begins timing at consent. Activity before consent is not replayed.
+Repeated grants and duplicate show callbacks do not create additional views.
+Clicks, page-internal tab changes, scrolling and element impressions still require
+manual events; this release does not automatically collect them.
+
+Upgrade the business mini program to `@entmesh/sdk-miniapp@0.2.1` to collect visible
+time. Earlier events retain their existing route, but no measured duration; reports
+display **未采集** rather than estimating time from neighboring timestamps.
+
+Examples written before the public release used `@entmesh/miniapp-sdk`. Update
+both the dependency name and imports to `@entmesh/sdk-miniapp`; the platform
+suffixes and client API remain the same. The public package is distributed through
+npmjs.org, so a CNB npm registry configuration is not required.
+
+## User properties (Proto 4.30)
+
+```ts
+await entmesh.identify('user-123', { plan: 'trial' })
+await entmesh.setUserProperties({ plan: 'pro' })
+await entmesh.unsetUserProperties(['legacy_tier'])
+await entmesh.flush()
+```
+
+Enable the profile platform and organization entitlement before using these APIs. Attribute mutations use a dedicated transport and do not create behavior events or sessions. Set merges specified top-level fields; objects and arrays replace the previous whole value. Unset removes a key; explicit null remains an empty value. Existing identify properties also populate the profile; ordinary event properties do not.
+
+Public clients require an identified user and granted consent. Business entities and directed relationships are authored only through server APIs, after their types are registered in the project profile catalog.
+
+## Development and releases
+
+Node.js 22 or later is required. Tests run from a standalone checkout; the HPKE
+interoperability fixture is included under `test/fixtures` with its protocol version.
+
+```sh
+npm ci
+npm test
+npm run lint
+npm run build
+npm run check:package
+```
+
+`package.json` is the version source. Both `npm version` and `npm run build`
+synchronize `VERSION` and the generated runtime constant in `src/version.ts`.
+
+Pushes and pull requests targeting `main` or `develop` only validate the SDK.
+Pushing a stable `vX.Y.Z` tag runs the release pipeline, sets the package version
+before testing and building,
+and publishes `@entmesh/sdk-miniapp` publicly to npmjs.org. The first release is
+`v0.2.0`; preparing an already-matching package version is supported. Publishing a
+version that already exists on npm fails instead of silently skipping it.
+
+Before pushing a release tag, create `sdk-miniapp-npm.yml` on the `main` branch of
+the `mliev/keywords` secret repository:
+
+```yaml
+NPM_TOKEN: "<npm granular publishing token>"
+allow_slugs:
+  - mliev/entmesh/sdk-miniapp
+```
+
+The token must have publishing access to the `@entmesh` scope and Bypass 2FA enabled
+for automated publishing. Configure the actual value only in the secret repository.
+Only the publish step imports it. `npm run publish:npm` checks the package, uses a
+temporary npm configuration containing an environment-variable reference, and
+removes that configuration on exit. The token is never written to the SDK source
+or printed by the publishing script.
+
+### Publish a new version
+
+Run from a clean `main` checkout. The example uses `0.2.2`; replace it with the
+next unused stable version.
+
+```sh
+release_version=0.2.2
+npm ci
+npm version "$release_version" --no-git-tag-version --allow-same-version
+npm test
+npm run lint
+npm run build
+npm run check:package
+git add package.json package-lock.json VERSION src/version.ts
+git commit -m "chore: prepare sdk-miniapp $release_version"
+git push origin main
+```
+
+After the `main` quality pipeline succeeds, publish its version tag:
+
+```sh
+git tag -a "v$release_version" -m "Release @entmesh/sdk-miniapp $release_version"
+git push origin "refs/tags/v$release_version"
+```
+
+The tag pipeline validates the tag, installs dependencies, synchronizes versions,
+runs tests and type checking, builds, checks package contents, and publishes with
+public access. Package checks cover the three platform entries, declarations,
+runtime version, and the files included in the npm package.
+
+### Verify publication and troubleshoot
+
+Check the release pipeline and then verify the public registry:
+
+```sh
+npm view "@entmesh/sdk-miniapp@$release_version" version dist.integrity --registry=https://registry.npmjs.org/ --prefer-online
+```
+
+In a separate consumer project, install the published version and check its imports:
+
+```sh
+npm install "@entmesh/sdk-miniapp@$release_version" --registry=https://registry.npmjs.org/
+node --input-type=module <<'JS'
+for (const platform of ['wechat', 'alipay', 'douyin']) {
+  const sdk = await import('@entmesh/sdk-miniapp/' + platform)
+  if (typeof sdk.createClient !== 'function') throw new Error(platform)
+  console.log(platform + ': import OK')
+}
+JS
+```
+
+- If npm reports that the package is being processed, publication has been accepted
+  but registry queries or installs may temporarily return 404. Wait and repeat the
+  registry and consumer checks before declaring the version available.
+- A missing `NPM_TOKEN` stops publication. Check the secret file URL, its
+  `allow_slugs`, and the token's scope permissions and expiration.
+- An already-published version cannot be overwritten. Use a new version and tag;
+  do not move the existing release tag.
+- HPKE tests must read the committed `test/fixtures/hpke-browser-v1.json`. Do not
+  restore a dependency on a sibling `proto` checkout. The cross-repository E2E
+  contract test checks this copy against the protocol source.

package/dist/alipay.d.ts

@@ -0,0 +1,4 @@
+import { MiniProgramClient } from './core.js';
+import type { MiniProgramOptions } from './types.js';
+export declare function createClient(options: MiniProgramOptions): MiniProgramClient;
+export type { ConsentState, MiniProgramOptions, Properties } from './types.js';

package/dist/alipay.js

@@ -0,0 +1,8 @@
+import { MiniProgramClient, installLifecycle } from './core.js';
+import { runtimeAdapter } from './runtime.js';
+export function createClient(options) {
+    const client = new MiniProgramClient(runtimeAdapter(globalThis.my, 'alipay_mini_program'), options);
+    if (options.autocapture !== false)
+        installLifecycle(client);
+    return client;
+}

package/dist/core.d.ts

@@ -0,0 +1,39 @@
+import type { ConsentState, MiniProgramOptions, Properties, RuntimeAdapter } from './types.js';
+export declare class MiniProgramClient {
+    private readonly adapter;
+    private readonly options;
+    private consentState;
+    private queue;
+    private anonymous;
+    private session;
+    private user?;
+    private timer?;
+    private sending?;
+    private key?;
+    private readonly ready;
+    private recording;
+    private consentGeneration;
+    private readonly lifecycle;
+    constructor(adapter: RuntimeAdapter, options: MiniProgramOptions);
+    private initialize;
+    track(eventName: string, properties?: Properties): Promise<void>;
+    page(route: string, properties?: Properties): Promise<void>;
+    screen(route: string, properties?: Properties): Promise<void>;
+    identify(userID: string, properties?: Properties): Promise<void>;
+    setUserProperties(properties: Properties): Promise<void>;
+    unsetUserProperties(keys: string[]): Promise<void>;
+    private profileMutation;
+    reset(): Promise<void>;
+    consent(state: ConsentState): Promise<void>;
+    refreshDeviceIdentifiers(): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    private record;
+    private capture;
+    private deliver;
+    private discovery;
+    private readQueue;
+    private persistQueue;
+    private id;
+}
+export declare function installLifecycle(client: MiniProgramClient): void;

package/dist/core.js

@@ -0,0 +1,209 @@
+import { decodeBase64url, encryptedEnvelope, sealHPKE, utf8 } from './hpke.js';
+import { SDK_VERSION } from './version.js';
+import { LifecycleTracker } from './lifecycle.js';
+const ANONYMOUS_KEY = 'entmesh_anonymous_id';
+const SESSION_KEY = 'entmesh_session';
+const QUEUE_KEY = 'entmesh_event_queue';
+const SESSION_TIMEOUT = 30 * 60 * 1000;
+const QUEUE_LIMIT = 500;
+const lifecycleTrackers = new WeakMap();
+export class MiniProgramClient {
+    constructor(adapter, options) {
+        this.adapter = adapter;
+        this.options = options;
+        this.anonymous = '';
+        this.session = { id: '', lastActivity: 0 };
+        this.recording = Promise.resolve();
+        this.consentGeneration = 0;
+        if (!options.clientKey.startsWith('ck_'))
+            throw new Error('clientKey must be a ck_ key');
+        if (!/^https:\/\//.test(options.endpoint) && !/^http:\/\/localhost(?::\d+)?$/.test(options.endpoint))
+            throw new Error('endpoint must use HTTPS');
+        this.consentState = options.consent ?? 'pending';
+        this.queue = this.readQueue();
+        this.lifecycle = new LifecycleTracker(this.consentState === 'grant', (type, name, properties, page) => this.capture(type, name, properties, page), () => this.flush());
+        lifecycleTrackers.set(this, this.lifecycle);
+        this.ready = this.initialize();
+        void this.ready.catch(() => undefined);
+    }
+    async initialize() {
+        this.anonymous = String(this.adapter.getStorage(ANONYMOUS_KEY) || '') || await this.id();
+        this.adapter.setStorage(ANONYMOUS_KEY, this.anonymous);
+        const stored = this.adapter.getStorage(SESSION_KEY);
+        const now = Date.now();
+        this.session = stored?.id && now - stored.lastActivity < SESSION_TIMEOUT ? stored : { id: await this.id(), lastActivity: now };
+        this.adapter.setStorage(SESSION_KEY, this.session);
+        this.timer = setInterval(() => { void this.flush(); }, this.options.flushIntervalMs ?? 5000);
+    }
+    async track(eventName, properties = {}) { await this.capture('track', eventName, properties); }
+    async page(route, properties = {}) {
+        const page = this.lifecycle.setPage(route, properties);
+        await this.capture('page', '$page_view', { ...properties, route }, page);
+    }
+    async screen(route, properties = {}) { await this.page(route, properties); }
+    async identify(userID, properties = {}) {
+        const value = userID.trim();
+        if (!value)
+            throw new Error('userID is required');
+        this.user = value;
+        await this.capture('identify', '$identify', properties);
+    }
+    async setUserProperties(properties) { await this.profileMutation('set', properties); }
+    async unsetUserProperties(keys) { await this.profileMutation('unset', undefined, keys); }
+    async profileMutation(operation, properties, unset) {
+        if (this.consentState !== 'grant')
+            return;
+        const user = this.user;
+        const generation = this.consentGeneration;
+        if (!user)
+            throw new Error('identify a user before updating properties');
+        const occurredAt = new Date().toISOString();
+        const values = properties ? JSON.parse(JSON.stringify(properties)) : undefined;
+        const keys = unset ? [...unset] : undefined;
+        await this.record(async () => {
+            if (generation !== this.consentGeneration || this.consentState !== 'grant')
+                return;
+            if (this.queue.length >= QUEUE_LIMIT)
+                throw new Error('profile queue is full');
+            const mutationID = await this.id();
+            if (generation !== this.consentGeneration || this.consentState !== 'grant')
+                return;
+            this.queue.push({ mutation_id: mutationID, occurred_at: occurredAt, subject: { kind: 'user', id: user }, operation, ...(values ? { properties: values } : {}), ...(keys ? { unset: keys } : {}) });
+            this.persistQueue();
+        });
+        if (this.queue.length >= (this.options.batchSize ?? 20))
+            await this.flush();
+    }
+    async reset() {
+        this.user = undefined;
+        await this.ready;
+        await this.recording;
+        this.anonymous = await this.id();
+        this.session = { id: await this.id(), lastActivity: Date.now() };
+        this.adapter.setStorage(ANONYMOUS_KEY, this.anonymous);
+        this.adapter.setStorage(SESSION_KEY, this.session);
+    }
+    async consent(state) {
+        if (this.consentState !== state)
+            this.consentGeneration++;
+        this.consentState = state;
+        const lifecycle = this.lifecycle.setConsent(state === 'grant');
+        if (state === 'deny' || state === 'revoke') {
+            this.queue = [];
+            this.persistQueue();
+            if (state === 'revoke') {
+                this.adapter.removeStorage(ANONYMOUS_KEY);
+                this.adapter.removeStorage(SESSION_KEY);
+                await this.reset();
+            }
+            return;
+        }
+        if (state === 'grant') {
+            await lifecycle;
+            await this.flush();
+        }
+    }
+    async refreshDeviceIdentifiers() { }
+    async flush() {
+        await this.ready;
+        await this.recording;
+        while (this.sending)
+            await this.sending;
+        if (this.consentState !== 'grant' || this.queue.length === 0)
+            return;
+        this.sending = (async () => { let remaining = this.queue.length; while (remaining > 0 && this.consentState === 'grant') {
+            const before = this.queue.length;
+            await this.deliver();
+            const sent = before - this.queue.length;
+            if (sent <= 0)
+                break;
+            remaining -= sent;
+        } })().finally(() => { this.sending = undefined; });
+        return this.sending;
+    }
+    async shutdown() { await this.ready; if (this.timer)
+        clearInterval(this.timer); await this.flush(); }
+    record(action) {
+        const pending = this.recording.then(() => this.ready).then(action);
+        this.recording = pending.catch(() => undefined);
+        return pending;
+    }
+    async capture(type, eventName, properties, page = this.lifecycle.pageContext()) {
+        if (this.consentState !== 'grant')
+            return;
+        if (!/^[$A-Za-z][A-Za-z0-9_.-]{0,127}$/.test(eventName))
+            throw new Error('event name is invalid');
+        const now = Date.now();
+        const generation = this.consentGeneration;
+        const user = this.user;
+        const snapshot = { ...page };
+        const endsVisibleInterval = eventName === '$visibility' || eventName === '$page_exit';
+        const values = JSON.parse(JSON.stringify(properties));
+        await this.record(async () => {
+            if (generation !== this.consentGeneration || this.consentState !== 'grant')
+                return;
+            if (!this.session.id || (!endsVisibleInterval && now - this.session.lastActivity >= SESSION_TIMEOUT))
+                this.session = { id: await this.id(), lastActivity: now };
+            this.session.lastActivity = now;
+            this.adapter.setStorage(SESSION_KEY, this.session);
+            const event = {
+                message_id: await this.id(), type, event_name: eventName, occurred_at: new Date(now).toISOString(),
+                anonymous_id: this.anonymous, session_id: this.session.id, properties: values,
+                context: { sdk: { name: 'entmesh-miniapp', version: SDK_VERSION }, device: this.adapter.systemContext(), ...(snapshot.path ? { page: snapshot } : {}) },
+            };
+            if (user)
+                event.user_id = user;
+            if (generation !== this.consentGeneration || this.consentState !== 'grant')
+                return;
+            if (this.queue.length >= QUEUE_LIMIT)
+                this.queue.shift();
+            this.queue.push(event);
+            this.persistQueue();
+        });
+        if (this.queue.length >= (this.options.batchSize ?? 20))
+            await this.flush();
+    }
+    async deliver() {
+        const profile = 'mutation_id' in this.queue[0];
+        const events = this.queue.slice(0, this.options.batchSize ?? 20).filter((item, index, items) => items.slice(0, index + 1).every((record) => ('mutation_id' in record) === profile));
+        const batchID = await this.id();
+        const batch = JSON.stringify({
+            schema_version: '1', batch_id: batchID, sent_at: new Date().toISOString(),
+            client: { platform: this.adapter.platform, application_id: this.options.applicationId, app_version: this.options.appVersion, sdk_name: 'entmesh-miniapp', sdk_version: SDK_VERSION },
+            ...(profile ? { mutations: events } : { events }),
+        });
+        try {
+            const discovery = await this.discovery();
+            const info = utf8(`entmesh-client-${profile ? "profile" : "batch"}-v1\0${discovery.kid}\0${this.options.clientKey}`);
+            const ciphertext = await sealHPKE(decodeBase64url(discovery.public_key), info, utf8(batch), (length) => this.adapter.randomBytes(length));
+            const response = await this.adapter.request({ url: `${this.options.endpoint.replace(/\/$/, '')}/v1/client/${profile ? "profiles/" : ""}batch/${this.options.clientKey}`, method: 'POST', data: JSON.parse(encryptedEnvelope(discovery.kid, ciphertext)), headers: { 'content-type': 'application/json' } });
+            if (response.statusCode === 409) {
+                this.key = undefined;
+                return;
+            }
+            if (response.statusCode < 200 || response.statusCode >= 300)
+                return;
+            this.queue = this.queue.filter(event => !events.includes(event));
+            this.persistQueue();
+        }
+        catch { /* Retain the persistent queue for the next bounded flush attempt. */ }
+    }
+    async discovery() {
+        if (this.key && this.key.expiresAt > Date.now())
+            return this.key.value;
+        const response = await this.adapter.request({ url: `${this.options.endpoint.replace(/\/$/, '')}/v1/browser-encryption-key`, method: 'GET' });
+        if (response.statusCode !== 200 || !response.data || typeof response.data !== 'object')
+            throw new Error('encryption key discovery failed');
+        const value = response.data;
+        if (value.version !== '1' || !value.kid || !value.public_key || value.suite?.kem !== 'DHKEM_P256_HKDF_SHA256' || value.suite?.kdf !== 'HKDF_SHA256' || value.suite?.aead !== 'AES_256_GCM')
+            throw new Error('encryption key discovery is invalid');
+        this.key = { value, expiresAt: Date.now() + 5 * 60 * 1000 };
+        return value;
+    }
+    readQueue() { const value = this.adapter.getStorage(QUEUE_KEY); return Array.isArray(value) ? value.slice(-QUEUE_LIMIT) : []; }
+    persistQueue() { this.adapter.setStorage(QUEUE_KEY, this.queue); }
+    async id() { return Array.from(await this.adapter.randomBytes(16), (value) => value.toString(16).padStart(2, '0')).join(''); }
+}
+export function installLifecycle(client) {
+    lifecycleTrackers.get(client)?.install();
+}

package/dist/douyin.d.ts

@@ -0,0 +1,4 @@
+import { MiniProgramClient } from './core.js';
+import type { MiniProgramOptions } from './types.js';
+export declare function createClient(options: MiniProgramOptions): MiniProgramClient;
+export type { ConsentState, MiniProgramOptions, Properties } from './types.js';

package/dist/douyin.js

@@ -0,0 +1,8 @@
+import { MiniProgramClient, installLifecycle } from './core.js';
+import { runtimeAdapter } from './runtime.js';
+export function createClient(options) {
+    const client = new MiniProgramClient(runtimeAdapter(globalThis.tt, 'douyin_mini_program'), options);
+    if (options.autocapture !== false)
+        installLifecycle(client);
+    return client;
+}

package/dist/hpke.d.ts

@@ -0,0 +1,5 @@
+export declare function utf8(value: string): Uint8Array;
+export declare function concat(...values: Uint8Array[]): Uint8Array;
+export declare function decodeBase64url(value: string): Uint8Array;
+export declare function sealHPKE(recipientPublicKey: Uint8Array, info: Uint8Array, plaintext: Uint8Array, randomBytes: (length: number) => Promise<Uint8Array>): Promise<Uint8Array>;
+export declare function encryptedEnvelope(kid: string, ciphertext: Uint8Array): string;

package/dist/hpke.js

@@ -0,0 +1,100 @@
+import { gcm } from '@noble/ciphers/aes.js';
+import { p256 } from '@noble/curves/nist.js';
+import { expand, extract } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+const VERSION = utf8('HPKE-v1');
+const KEM_SUITE = concat(utf8('KEM'), i2osp(0x0010, 2));
+const HPKE_SUITE = concat(utf8('HPKE'), i2osp(0x0010, 2), i2osp(0x0001, 2), i2osp(0x0002, 2));
+export function utf8(value) {
+    const encoded = unescape(encodeURIComponent(value));
+    return Uint8Array.from(encoded, (character) => character.charCodeAt(0));
+}
+export function concat(...values) {
+    const output = new Uint8Array(values.reduce((sum, value) => sum + value.length, 0));
+    let offset = 0;
+    for (const value of values) {
+        output.set(value, offset);
+        offset += value.length;
+    }
+    return output;
+}
+function i2osp(value, length) {
+    const result = new Uint8Array(length);
+    for (let index = length - 1; index >= 0; index--) {
+        result[index] = value & 0xff;
+        value >>>= 8;
+    }
+    return result;
+}
+function labeledExtract(suite, salt, label, ikm) {
+    return extract(sha256, concat(VERSION, suite, utf8(label), ikm), salt);
+}
+function labeledExpand(suite, prk, label, info, length) {
+    return expand(sha256, prk, concat(i2osp(length, 2), VERSION, suite, utf8(label), info), length);
+}
+function base64url(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let output = '';
+    for (let offset = 0; offset < bytes.length; offset += 3) {
+        const a = bytes[offset] ?? 0, b = bytes[offset + 1] ?? 0, c = bytes[offset + 2] ?? 0;
+        const value = (a << 16) | (b << 8) | c;
+        output += alphabet[(value >>> 18) & 63] + alphabet[(value >>> 12) & 63];
+        if (offset + 1 < bytes.length)
+            output += alphabet[(value >>> 6) & 63];
+        if (offset + 2 < bytes.length)
+            output += alphabet[value & 63];
+    }
+    return output;
+}
+export function decodeBase64url(value) {
+    if (!/^[A-Za-z0-9_-]+$/.test(value))
+        throw new Error('invalid base64url');
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    const output = [];
+    let buffer = 0, bits = 0;
+    for (const character of value) {
+        const index = alphabet.indexOf(character);
+        if (index < 0)
+            throw new Error('invalid base64url');
+        buffer = (buffer << 6) | index;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            output.push((buffer >>> bits) & 0xff);
+        }
+    }
+    return Uint8Array.from(output);
+}
+export async function sealHPKE(recipientPublicKey, info, plaintext, randomBytes) {
+    if (recipientPublicKey.length !== 65 || recipientPublicKey[0] !== 4)
+        throw new Error('invalid recipient public key');
+    const ikm = await randomBytes(32);
+    const dkpPRK = labeledExtract(KEM_SUITE, new Uint8Array(), 'dkp_prk', ikm);
+    let secretKey;
+    for (let counter = 0; counter < 256 && !secretKey; counter++) {
+        const candidate = labeledExpand(KEM_SUITE, dkpPRK, 'candidate', Uint8Array.of(counter), 32);
+        try {
+            p256.getPublicKey(candidate, false);
+            secretKey = candidate;
+        }
+        catch { /* try the next deterministic candidate */ }
+    }
+    if (!secretKey)
+        throw new Error('secure random private key generation failed');
+    const enc = p256.getPublicKey(secretKey, false);
+    const dhPoint = p256.getSharedSecret(secretKey, recipientPublicKey, false);
+    const dh = dhPoint.slice(1, 33);
+    const kemContext = concat(enc, recipientPublicKey);
+    const eaePRK = labeledExtract(KEM_SUITE, new Uint8Array(), 'eae_prk', dh);
+    const sharedSecret = labeledExpand(KEM_SUITE, eaePRK, 'shared_secret', kemContext, 32);
+    const pskIDHash = labeledExtract(HPKE_SUITE, new Uint8Array(), 'psk_id_hash', new Uint8Array());
+    const infoHash = labeledExtract(HPKE_SUITE, new Uint8Array(), 'info_hash', info);
+    const keyScheduleContext = concat(Uint8Array.of(0), pskIDHash, infoHash);
+    const secret = labeledExtract(HPKE_SUITE, sharedSecret, 'secret', new Uint8Array());
+    const key = labeledExpand(HPKE_SUITE, secret, 'key', keyScheduleContext, 32);
+    const nonce = labeledExpand(HPKE_SUITE, secret, 'base_nonce', keyScheduleContext, 12);
+    return concat(enc, gcm(key, nonce, new Uint8Array()).encrypt(plaintext));
+}
+export function encryptedEnvelope(kid, ciphertext) {
+    return JSON.stringify({ version: '1', kid, ciphertext: base64url(ciphertext) });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { MiniProgramClient } from './core.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { MiniProgramClient } from './core.js';

package/dist/lifecycle.d.ts

@@ -0,0 +1,29 @@
+import type { Properties } from './types.js';
+export interface PageContext {
+    path: string;
+    title?: string;
+}
+type Emit = (type: 'page' | 'track', name: string, properties: Properties, page: PageContext) => Promise<void>;
+/** Owns visible intervals; App and Page callbacks can close the same interval safely. */
+export declare class LifecycleTracker {
+    private granted;
+    private readonly emit;
+    private readonly flush;
+    private readonly pages;
+    private active?;
+    private context;
+    private foreground?;
+    private started;
+    constructor(granted: boolean, emit: Emit, flush: () => Promise<void>);
+    pageContext(): PageContext;
+    setPage(path: string, properties?: Properties): PageContext;
+    setConsent(granted: boolean): Promise<void>;
+    private start;
+    private begin;
+    private finish;
+    private app;
+    private page;
+    private route;
+    install(): void;
+}
+export {};

package/dist/lifecycle.js

@@ -0,0 +1,147 @@
+/** Owns visible intervals; App and Page callbacks can close the same interval safely. */
+export class LifecycleTracker {
+    constructor(granted, emit, flush) {
+        this.granted = granted;
+        this.emit = emit;
+        this.flush = flush;
+        this.pages = new WeakMap();
+        this.context = { path: '' };
+        this.started = false;
+    }
+    pageContext() { return { ...this.context }; }
+    setPage(path, properties = {}) {
+        const title = typeof properties.title === 'string' ? properties.title : undefined;
+        this.context = { path, ...(title ? { title } : {}) };
+        if (this.active?.page.path === path)
+            this.active.page = this.pageContext();
+        return this.pageContext();
+    }
+    setConsent(granted) {
+        const changed = this.granted !== granted;
+        this.granted = granted;
+        if (!granted) {
+            if (this.active)
+                this.active.since = undefined;
+            return Promise.resolve();
+        }
+        const start = this.start();
+        const page = changed && this.active ? this.begin(this.active) : Promise.resolve();
+        return Promise.all([start, page]).then(() => undefined);
+    }
+    start() {
+        if (!this.granted || this.started)
+            return Promise.resolve();
+        this.started = true;
+        return this.emit('track', '$app_start', {}, this.pageContext());
+    }
+    begin(state) {
+        if (!this.granted || this.foreground === false || !state.shown || state.since !== undefined)
+            return Promise.resolve();
+        state.since = Date.now();
+        return this.emit('page', '$page_view', { route: state.page.path }, { ...state.page });
+    }
+    finish(state, name) {
+        if (!state)
+            return Promise.resolve();
+        const since = state.since;
+        state.since = undefined;
+        if (!this.granted || (since === undefined && name === '$visibility'))
+            return Promise.resolve();
+        const properties = { route: state.page.path };
+        if (since !== undefined)
+            properties.visible_ms = Math.max(0, Date.now() - since);
+        return this.emit('track', name, properties, { ...state.page });
+    }
+    app(handler, options) {
+        const path = options && typeof options === 'object' && 'path' in options && typeof options.path === 'string' ? options.path : '';
+        if (path && !this.active)
+            this.setPage(path);
+        if (handler === 'onLaunch')
+            return this.start();
+        if (handler === 'onShow') {
+            if (this.foreground === true)
+                return Promise.resolve();
+            this.foreground = true;
+            const foreground = this.emit('track', '$app_foreground', {}, this.pageContext());
+            const page = this.active && (!path || path === this.active.page.path) ? this.begin(this.active) : Promise.resolve();
+            return Promise.all([foreground, page]).then(() => undefined);
+        }
+        if (this.foreground === false)
+            return Promise.resolve();
+        this.foreground = false;
+        const visible = this.finish(this.active, '$visibility');
+        const background = this.emit('track', '$app_background', {}, this.pageContext());
+        return Promise.all([visible, background]).then(() => this.flush());
+    }
+    page(handler, owner) {
+        let state = this.pages.get(owner);
+        if (handler === 'onShow') {
+            const path = this.route(owner);
+            if (!state) {
+                state = { page: { path }, shown: false };
+                this.pages.set(owner, state);
+            }
+            const previous = this.active !== state ? this.finish(this.active, '$visibility') : Promise.resolve();
+            if (this.active && this.active !== state)
+                this.active.shown = false;
+            state.page = { ...state.page, path };
+            state.shown = true;
+            this.active = state;
+            this.context = { ...state.page };
+            return Promise.all([previous, this.begin(state)]).then(() => undefined);
+        }
+        if (!state)
+            return Promise.resolve();
+        state.shown = false;
+        const result = this.finish(state, handler === 'onUnload' ? '$page_exit' : '$visibility');
+        if (handler === 'onUnload') {
+            this.pages.delete(owner);
+            if (this.active === state)
+                this.active = undefined;
+        }
+        return result;
+    }
+    route(owner) {
+        const route = owner.route || owner.__route__;
+        if (typeof route === 'string')
+            return route;
+        const getPages = globalThis.getCurrentPages;
+        if (typeof getPages === 'function') {
+            try {
+                const pages = getPages();
+                const current = pages[pages.length - 1];
+                return String(current?.route || current?.__route__ || '');
+            }
+            catch { /* Some runtimes expose no page stack during registration. */ }
+        }
+        return '';
+    }
+    install() {
+        const root = globalThis;
+        for (const name of ['App', 'Page']) {
+            const original = root[name];
+            if (typeof original !== 'function' || original.__entmesh)
+                continue;
+            const tracker = this;
+            const wrapped = (options) => {
+                const next = { ...options };
+                const handlers = name === 'App' ? ['onLaunch', 'onShow', 'onHide'] : ['onShow', 'onHide', 'onUnload'];
+                for (const handler of handlers) {
+                    const existing = next[handler];
+                    next[handler] = function (...args) {
+                        // Analytics errors must not replace a business callback's return value or exception.
+                        try {
+                            const pending = name === 'App' ? tracker.app(handler, args[0]) : tracker.page(handler, this);
+                            void pending.catch(() => undefined);
+                        }
+                        catch { /* The application's lifecycle still runs if collection fails. */ }
+                        return typeof existing === 'function' ? existing.apply(this, args) : undefined;
+                    };
+                }
+                return original(next);
+            };
+            wrapped.__entmesh = true;
+            root[name] = wrapped;
+        }
+    }
+}

package/dist/profile-contract.d.ts

@@ -0,0 +1,29 @@
+import type { PropertyValue } from './types.js';
+export interface ProfileSubject {
+    kind: 'user' | 'entity';
+    id: string;
+    entity_type?: string;
+}
+export interface ProfileMutation {
+    mutation_id: string;
+    occurred_at: string;
+    subject: ProfileSubject;
+    operation: 'set' | 'unset' | 'entity_upsert' | 'link' | 'unlink';
+    properties?: Record<string, PropertyValue>;
+    unset?: string[];
+    relation_type?: string;
+    target?: ProfileSubject;
+}
+export interface ProfileBatch {
+    schema_version: '1';
+    batch_id: string;
+    sent_at: string;
+    client?: {
+        platform: string;
+        application_id: string;
+        app_version?: string;
+        sdk_name: string;
+        sdk_version: string;
+    };
+    mutations: ProfileMutation[];
+}

package/dist/profile-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { MiniProgramPlatform, RuntimeAdapter } from './types.js';
+type Runtime = Record<string, (...args: never[]) => unknown>;
+export declare function runtimeAdapter(runtime: Runtime, platform: MiniProgramPlatform): RuntimeAdapter;
+export {};

package/dist/runtime.js

@@ -0,0 +1,81 @@
+function callRequest(runtime, options) {
+    return new Promise((resolve, reject) => {
+        const request = runtime.request;
+        if (typeof request !== 'function') {
+            reject(new Error('mini-program request API is unavailable'));
+            return;
+        }
+        request.call(runtime, {
+            url: options.url, method: options.method, data: options.data,
+            header: options.headers, headers: options.headers,
+            dataType: options.method === 'GET' ? 'json' : 'text',
+            success: (result) => resolve({ statusCode: Number(result.statusCode ?? result.status ?? 0), data: result.data }),
+            fail: reject,
+        });
+    });
+}
+function secureRandom(runtime, length) {
+    return new Promise((resolve, reject) => {
+        const getRandomValues = runtime.getRandomValues;
+        if (typeof getRandomValues !== 'function') {
+            reject(new Error('secure random API is unavailable'));
+            return;
+        }
+        getRandomValues.call(runtime, {
+            length,
+            success: (result) => {
+                const value = result.randomValues ?? result.data;
+                if (value instanceof ArrayBuffer)
+                    resolve(new Uint8Array(value));
+                else if (ArrayBuffer.isView(value))
+                    resolve(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+                else
+                    reject(new Error('secure random API returned invalid bytes'));
+            },
+            fail: reject,
+        });
+    });
+}
+export function runtimeAdapter(runtime, platform) {
+    return {
+        platform,
+        request: (options) => callRequest(runtime, options),
+        getStorage(key) {
+            const value = typeof runtime.getStorageSync === 'function'
+                ? runtime.getStorageSync.call(runtime, (platform === 'alipay_mini_program' ? { key } : key))
+                : undefined;
+            if (value && typeof value === 'object' && 'data' in value)
+                return value.data;
+            return value;
+        },
+        setStorage(key, value) {
+            if (typeof runtime.setStorageSync !== 'function')
+                return;
+            if (platform === 'alipay_mini_program')
+                runtime.setStorageSync.call(runtime, { key, data: value });
+            else
+                runtime.setStorageSync.call(runtime, key, value);
+        },
+        removeStorage(key) {
+            if (typeof runtime.removeStorageSync !== 'function')
+                return;
+            if (platform === 'alipay_mini_program')
+                runtime.removeStorageSync.call(runtime, { key });
+            else
+                runtime.removeStorageSync.call(runtime, key);
+        },
+        randomBytes: (length) => secureRandom(runtime, length),
+        systemContext() {
+            for (const name of ['getDeviceInfo', 'getDeviceInfoSync', 'getSystemInfoSync']) {
+                const method = runtime[name];
+                if (typeof method === 'function') {
+                    try {
+                        return method.call(runtime);
+                    }
+                    catch { /* try the next supported API */ }
+                }
+            }
+            return {};
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+export type ConsentState = 'pending' | 'grant' | 'deny' | 'revoke';
+export type MiniProgramPlatform = 'wechat_mini_program' | 'alipay_mini_program' | 'douyin_mini_program';
+export type PropertyScalar = string | number | boolean | null;
+export type PropertyValue = PropertyScalar | PropertyScalar[] | Record<string, PropertyScalar>;
+export type Properties = Record<string, PropertyValue>;
+export interface MiniProgramOptions {
+    endpoint: string;
+    clientKey: string;
+    applicationId: string;
+    appVersion?: string;
+    consent?: ConsentState;
+    autocapture?: boolean;
+    flushIntervalMs?: number;
+    batchSize?: number;
+}
+export interface EventV1 {
+    message_id: string;
+    type: 'page' | 'track' | 'identify';
+    event_name: string;
+    occurred_at: string;
+    anonymous_id: string;
+    user_id?: string;
+    session_id: string;
+    properties: Properties;
+    context: Record<string, unknown>;
+}
+export interface RuntimeResponse {
+    statusCode: number;
+    data: unknown;
+}
+export interface RuntimeAdapter {
+    readonly platform: MiniProgramPlatform;
+    request(options: {
+        url: string;
+        method: 'GET' | 'POST';
+        data?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<RuntimeResponse>;
+    getStorage(key: string): unknown;
+    setStorage(key: string, value: unknown): void;
+    removeStorage(key: string): void;
+    randomBytes(length: number): Promise<Uint8Array>;
+    systemContext(): Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.2.1";

package/dist/version.js

@@ -0,0 +1,2 @@
+// Generated from package.json by scripts/sync-version.mjs.
+export const SDK_VERSION = '0.2.1';

package/dist/wechat.d.ts

@@ -0,0 +1,4 @@
+import { MiniProgramClient } from './core.js';
+import type { MiniProgramOptions } from './types.js';
+export declare function createClient(options: MiniProgramOptions): MiniProgramClient;
+export type { ConsentState, MiniProgramOptions, Properties } from './types.js';

package/dist/wechat.js

@@ -0,0 +1,8 @@
+import { MiniProgramClient, installLifecycle } from './core.js';
+import { runtimeAdapter } from './runtime.js';
+export function createClient(options) {
+    const client = new MiniProgramClient(runtimeAdapter(globalThis.wx, 'wechat_mini_program'), options);
+    if (options.autocapture !== false)
+        installLifecycle(client);
+    return client;
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@entmesh/sdk-miniapp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./wechat": {
+      "types": "./dist/wechat.d.ts",
+      "import": "./dist/wechat.js"
+    },
+    "./alipay": {
+      "types": "./dist/alipay.d.ts",
+      "import": "./dist/alipay.js"
+    },
+    "./douyin": {
+      "types": "./dist/douyin.d.ts",
+      "import": "./dist/douyin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/sync-version.mjs && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "version": "node scripts/sync-version.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "publish:npm": "node scripts/publish.mjs"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.0.1",
+    "@noble/curves": "^2.0.1",
+    "@noble/hashes": "^2.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}