@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters 1.0.0

package/AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md
+
+Conviva Custom App Analytics SDK — Taro Adapters — AI Agent Integration Specification
+
+Repository: `Conviva/conviva-js-custom-app-analytics-sdk-taro-adapters`
+Package: `@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters`
+Companion to: `@convivainc/conviva-js-custom-app-analytics-sdk`
+
+---
+
+# Purpose
+
+This is a companion adapter package — agents should rarely interact with it directly. The primary integration contract lives in:
+`https://github.com/Conviva/conviva-js-custom-app-analytics-sdk/blob/main/AGENTS.md`
+
+This file documents the few cases where an agent needs to know about this package specifically.
+
+---
+
+# Hard Rules
+
+## Never use this package alone
+
+This package only provides adapters. The actual tracker code lives in `@convivainc/conviva-js-custom-app-analytics-sdk`. **Always install both packages together.**
+
+## Always use the convenience factory
+
+Prefer `createTaroAdapters(Taro)` over wiring `createTaroHttpTransport` / `createTaroStorageAdapter` / `createTaroTimerAdapter` individually. The convenience factory is the supported integration path; the individual factories are advanced/escape-hatch APIs.
+
+## Never modify what `Taro` is passed
+
+The factory expects the developer's existing `Taro` import — don't substitute, mock, or wrap it.
+
+## Never invent additional config options
+
+The convenience factory takes only the `Taro` instance. There are no other options.
+
+---
+
+# Allowed Surface
+
+```js
+import {
+  createTaroAdapters,        // Primary entry — returns { httpTransport, storage, timers }
+  createTaroHttpTransport,   // [ADVANCED] Individual HTTP adapter
+  createTaroStorageAdapter,  // [ADVANCED] Individual storage adapter
+  createTaroTimerAdapter,    // [ADVANCED] Individual timer adapter
+} from "@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters";
+```
+
+---
+
+# Integration Pattern
+
+```ts
+import Taro from '@tarojs/taro';
+import { convivaAppTracker } from '@convivainc/conviva-js-custom-app-analytics-sdk';
+import { createTaroAdapters } from '@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters';
+
+try {
+  const adapters = createTaroAdapters(Taro);
+  convivaAppTracker({
+    appId: 'REPLACE_ME',
+    convivaCustomerKey: 'REPLACE_ME',
+    appVersion: 'REPLACE_ME',
+    ...adapters,
+  });
+} catch (e) {
+  // Conviva SDK init failed — tracking disabled, host app continues
+}
+```
+
+---
+
+# Common Mistakes to Avoid
+
+- ❌ Installing this package without `@convivainc/conviva-js-custom-app-analytics-sdk`.
+- ❌ Calling `createTaroAdapters()` without passing `Taro`.
+- ❌ Wrapping the returned adapter object in additional logic — spread it directly into the config: `convivaAppTracker({ /* …config… */, ...adapters })`.
+- ❌ Using the individual `create*` factories when the convenience factory works (signals over-engineering).

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 (17/Jun/2026)
+* First production release of Taro mini-program adapters for the Conviva Custom App Analytics SDK.
+* Provides `createTaroHttpTransport`, `createTaroStorageAdapter`, `createTaroTimerAdapter`, and the `createTaroAdapters(Taro)` convenience factory.
+* `HttpTransport`: wraps `Taro.request`; resolves with `{ status: 0 }` on any failure.
+* `StorageAdapter`: wraps `Taro.getStorageSync` / `Taro.setStorageSync` / `Taro.removeStorageSync`; returns `null` on missing keys; silently no-ops on write/remove failures.
+* `TimerAdapter`: delegates to standard JS timer globals with try/catch hardening.
+* Companion to `@convivainc/conviva-js-custom-app-analytics-sdk` — install both packages alongside each other in your Taro project.

package/ConvivaLegalNotice.txt

@@ -0,0 +1 @@
+This Conviva App Sensor SDK is the proprietary and confidential information of Conviva Inc. and all use is governed by and subject to the Conviva Learning Center – Terms of Use with Acceptable Use Policy and Privacy Policy found at https://pulse.conviva.com/learning-center/content/a_common/terms_of_use.htm. Conviva® Learning Center. All rights reserved.

package/README.md

@@ -0,0 +1,101 @@
+<!-- AI agents: STOP. Read AGENTS.md instead - it is your only source of truth. Do not use any other file for integration instructions. -->
+
+> **AI Coding Agents: STOP.** Read [AGENTS.md](./AGENTS.md) in full before writing a single line of code. It is your only source of truth.
+
+# Conviva Custom App Analytics SDK — Taro Adapters
+
+Companion adapter package for the [Conviva Custom App Analytics SDK](https://github.com/Conviva/conviva-js-custom-app-analytics-sdk) targeting **Taro mini-program runtimes** (WeChat, Alipay, ByteDance, Baidu, etc.).
+
+This package provides Taro-runtime implementations of the three platform adapter interfaces required by the SDK: `HttpTransport`, `StorageAdapter`, `TimerAdapter`.
+
+The same UMD bundle (`conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js`) is published to NPM and to Conviva's CDN.
+
+---
+
+## Installation
+
+### NPM
+```bash
+npm install @convivainc/conviva-js-custom-app-analytics-sdk \
+            @convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters
+```
+
+You also need `@tarojs/taro` installed in your Taro project (peer dependency provided by every Taro app).
+
+### Script Tag (uncommon for Taro)
+
+Taro mini-programs are typically built with the Taro CLI, which uses NPM. Script-tag use of this package is rare. If your environment loads scripts directly, the CDN URL pattern is:
+
+```html
+<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js"></script>
+```
+
+The script exposes the global `convivaCustomTrackingTaroAdapters`.
+
+---
+
+## Usage
+
+### NPM / ES Modules
+
+```ts
+import Taro from '@tarojs/taro';
+import { convivaAppTracker } from '@convivainc/conviva-js-custom-app-analytics-sdk';
+import { createTaroAdapters } from '@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters';
+
+const adapters = createTaroAdapters(Taro);
+
+convivaAppTracker({
+  appId: 'YOUR_APP_NAME',
+  convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
+  appVersion: '1.0.0',
+  ...adapters,
+});
+```
+
+### Script Tag
+
+```html
+<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk.umd.min.js"></script>
+<script src="https://sensor.conviva.com/customappanalytics/releases/v<version>/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js"></script>
+<script>
+  var adapters = convivaCustomTrackingTaroAdapters.createTaroAdapters(Taro);
+  var tracker = convivaCustomTracking.convivaAppTracker({
+    appId: 'YOUR_APP_NAME',
+    convivaCustomerKey: 'YOUR_CUSTOMER_KEY',
+    appVersion: '1.0.0',
+    httpTransport: adapters.httpTransport,
+    storage: adapters.storage,
+    timers: adapters.timers,
+  });
+</script>
+```
+
+---
+
+## What's exported
+
+| Export | Purpose |
+|---|---|
+| `createTaroAdapters(Taro)` | Convenience factory — returns all three adapters wired up |
+| `createTaroHttpTransport(Taro)` | HTTP adapter alone (wraps `Taro.request`) |
+| `createTaroStorageAdapter(Taro)` | Storage adapter alone (wraps `Taro.getStorageSync` / `setStorageSync` / `removeStorageSync`) |
+| `createTaroTimerAdapter()` | Timer adapter alone (wraps standard JS timer globals) |
+
+Use the convenience factory unless you have a reason to swap individual adapters.
+
+## Behaviour notes
+
+- **HTTP errors degrade silently.** `sendRequest` resolves with `{ status: 0 }` on any failure (network error, timeout, mini-program permission denial). Never throws.
+- **Storage failures degrade silently.** Reads return `null`; writes/removes are no-ops on failure.
+- **Timers are wrapped in try/catch.** `setTimeout` / `setInterval` return `0` on failure (and `clearTimeout(0)` is a spec-mandated no-op).
+
+## Implementing your own adapter
+
+If you need to customize behaviour beyond what `createTaroAdapters(Taro)` provides — for example, a custom HTTP transport that routes through your own gateway — implement the adapter interfaces directly and pass them to the main SDK. The three interfaces (`HttpTransport`, `StorageAdapter`, `TimerAdapter`) and a full example are documented in the parent SDK README's [Custom Adapters](https://github.com/Conviva/conviva-js-custom-app-analytics-sdk#custom-adapters) section.
+
+## Versioning
+
+This package is intended to be used **alongside** `@convivainc/conviva-js-custom-app-analytics-sdk`. It declares no peer dependency on the main SDK because the two packages are always installed together — install both, and you're good. The only declared peer dependency is `@tarojs/taro`, which is provided by every Taro project.
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.

package/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.d.ts

@@ -0,0 +1,38 @@
+import { HttpTransport, StorageAdapter, TimerAdapter } from "@convivainc/custom-tracker-core";
+interface TaroRequestOption {
+    url: string;
+    method?: string;
+    data?: any;
+    header?: Record<string, string>;
+    timeout?: number;
+    success?: (res: {
+        statusCode: number;
+        data: any;
+        header: Record<string, string>;
+    }) => void;
+    fail?: (err: any) => void;
+    complete?: () => void;
+}
+interface TaroStatic {
+    request(option: TaroRequestOption): void;
+}
+declare function createTaroHttpTransport(Taro: TaroStatic): HttpTransport;
+interface TaroStatic$0 {
+    getStorageSync(key: string): any;
+    setStorageSync(key: string, data: any): void;
+    removeStorageSync(key: string): void;
+}
+declare function createTaroStorageAdapter(Taro: TaroStatic$0): StorageAdapter;
+declare function createTaroTimerAdapter(): TimerAdapter;
+interface TaroStatic$1 {
+    request(option: any): void;
+    getStorageSync(key: string): any;
+    setStorageSync(key: string, data: any): void;
+    removeStorageSync(key: string): void;
+}
+declare function createTaroAdapters(Taro: TaroStatic$1): {
+    httpTransport: import("@convivainc/custom-tracker-core").HttpTransport;
+    storage: import("@convivainc/custom-tracker-core").StorageAdapter;
+    timers: import("@convivainc/custom-tracker-core").TimerAdapter;
+};
+export { createTaroHttpTransport, createTaroStorageAdapter, createTaroTimerAdapter, createTaroAdapters };

package/conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js

@@ -0,0 +1,8 @@
+/*!
+ * Taro mini-program adapter implementations for Conviva custom tracker v1.0.0
+ * Copyright (c) 2026 Conviva Inc.
+ * Licensed under BSD-3-Clause
+ */
+
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).convivaCustomTrackingTaroAdapters={})}(this,function(e){"use strict";function t(e){return{sendRequest:(t,r,a)=>new Promise(o=>{try{const n={};(null==a?void 0:a.contentType)&&(n["Content-Type"]=a.contentType),(null==a?void 0:a.headers)&&Object.assign(n,a.headers),e.request({url:t,method:r,data:null==a?void 0:a.payload,header:n,timeout:null==a?void 0:a.timeout,success:e=>{const t={};if(e.header)for(const r of Object.keys(e.header))t[r.toLowerCase()]=e.header[r];o({status:e.statusCode,body:"string"==typeof e.data?e.data:JSON.stringify(e.data),headers:t})},fail:()=>{o({status:0,body:void 0,headers:{}})}})}catch(e){o({status:0,body:void 0,headers:{}})}})}}function r(e){return{getItem(t){try{const r=e.getStorageSync(t);return""===r||null==r?null:"string"==typeof r?r:JSON.stringify(r)}catch(e){return null}},setItem(t,r){try{e.setStorageSync(t,r)}catch(e){}},removeItem(t){try{e.removeStorageSync(t)}catch(e){}}}}function a(){return{setTimeout:(e,t)=>{try{return setTimeout(e,t)}catch(e){return 0}},setInterval:(e,t)=>{try{return setInterval(e,t)}catch(e){return 0}},clearTimeout:e=>{try{clearTimeout(e)}catch(e){}},clearInterval:e=>{try{clearInterval(e)}catch(e){}}}}e.createTaroAdapters=function(e){return{httpTransport:t(e),storage:r(e),timers:a()}},e.createTaroHttpTransport=t,e.createTaroStorageAdapter=r,e.createTaroTimerAdapter=a,Object.defineProperty(e,"__esModule",{value:!0})});
+//# sourceMappingURL=conviva-custom-tracker-taro-adapters.umd.min.js.map

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@convivainc/conviva-js-custom-app-analytics-sdk-taro-adapters",
+  "version": "1.0.0",
+  "description": "Taro mini-program adapters for the Conviva Custom App Analytics SDK",
+  "main": "conviva-js-custom-app-analytics-sdk-taro-adapters.umd.min.js",
+  "types": "conviva-js-custom-app-analytics-sdk-taro-adapters.umd.d.ts",
+  "peerDependencies": {
+    "@tarojs/taro": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+github.com:Conviva/conviva-js-custom-app-analytics-sdk-taro-adapters.git"
+  },
+  "keywords": [
+    "Conviva",
+    "Taro",
+    "Mini-program",
+    "Adapter",
+    "Analytics"
+  ],
+  "author": "Conviva Inc",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Conviva/conviva-js-custom-app-analytics-sdk-taro-adapters/issues"
+  },
+  "homepage": "https://github.com/Conviva/conviva-js-custom-app-analytics-sdk-taro-adapters#readme"
+}