@entmesh/sdk-miniapp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,79 @@
-# 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.
+
+Install from the public npm registry:
+
+```sh
+npm install @entmesh/sdk-miniapp --registry=https://registry.npmjs.org/
+```
+
+```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.
+
+Use `@entmesh/sdk-miniapp/alipay` for Alipay or `@entmesh/sdk-miniapp/douyin` for Douyin. Each entry exports `createClient` and the platform-independent option types.
+
+## User properties (Proto 4.30)
+
+```ts
+await client.identify('user-123', { plan: 'trial' })
+await client.setUserProperties({ plan: 'pro' })
+await client.unsetUserProperties(['legacy_tier'])
+await client.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`.
+
+Branch pushes and pull requests 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.

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,35 @@
+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 appStartSent;
+    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 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,198 @@
+import { decodeBase64url, encryptedEnvelope, sealHPKE, utf8 } from './hpke.js';
+import { SDK_VERSION } from './version.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;
+export class MiniProgramClient {
+    constructor(adapter, options) {
+        this.adapter = adapter;
+        this.options = options;
+        this.anonymous = '';
+        this.session = { id: '', lastActivity: 0 };
+        this.appStartSent = false;
+        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();
+        void this.initialize();
+    }
+    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 = {}) { await this.capture('page', '$page_view', { route, ...properties }); }
+    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;
+        if (!user)
+            throw new Error('identify a user before updating properties');
+        if (this.queue.length >= QUEUE_LIMIT)
+            throw new Error('profile queue is full');
+        this.queue.push({ mutation_id: await this.id(), occurred_at: new Date().toISOString(), subject: { kind: 'user', id: user }, operation, ...(properties ? { properties: JSON.parse(JSON.stringify(properties)) } : {}), ...(unset ? { unset: [...unset] } : {}) });
+        this.persistQueue();
+        if (this.queue.length >= (this.options.batchSize ?? 20))
+            await this.flush();
+    }
+    async reset() {
+        this.user = undefined;
+        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) {
+        this.consentState = state;
+        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') {
+            if (!this.appStartSent) {
+                this.appStartSent = true;
+                await this.capture('track', '$app_start', {});
+            }
+            await this.flush();
+        }
+    }
+    async refreshDeviceIdentifiers() { }
+    async flush() {
+        if (this.consentState !== 'grant' || this.queue.length === 0)
+            return;
+        if (this.sending)
+            return this.sending;
+        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() { if (this.timer)
+        clearInterval(this.timer); await this.flush(); }
+    async capture(type, eventName, properties) {
+        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();
+        if (!this.session.id || 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 || await this.id(), session_id: this.session.id, properties,
+            context: { sdk: { name: 'entmesh-miniapp', version: SDK_VERSION }, device: this.adapter.systemContext() },
+        };
+        if (this.user)
+            event.user_id = this.user;
+        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.splice(0, events.length);
+            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) {
+    const root = globalThis;
+    const wrap = (name) => {
+        const original = root[name];
+        if (typeof original !== 'function' || original.__entmesh)
+            return;
+        const wrapped = (options) => {
+            const next = { ...options };
+            const handlers = name === 'App'
+                ? { onLaunch: '$app_start', onShow: '$app_foreground', onHide: '$app_background' }
+                : { onShow: '$page_view', onHide: '$visibility', onUnload: '$page_exit' };
+            for (const [handler, eventName] of Object.entries(handlers)) {
+                const existing = next[handler];
+                next[handler] = function (...args) {
+                    const route = String(this.route || this.__route__ || '');
+                    if (eventName === '$page_view')
+                        void client.page(route);
+                    else
+                        void client.track(eventName, route ? { route } : {});
+                    if (eventName === '$app_background')
+                        void client.flush();
+                    return typeof existing === 'function' ? existing.apply(this, args) : undefined;
+                };
+            }
+            return original(next);
+        };
+        wrapped.__entmesh = true;
+        root[name] = wrapped;
+    };
+    wrap('App');
+    wrap('Page');
+}

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/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.0";

package/dist/version.js

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

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.0",
+  "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"
+  }
+}