@wireai/activation 0.1.0

package/dist/types-GL_hQ0TN.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared types for the coachmark / guided-tour overlay engine.
+ *
+ * Lifted from the Myelino app engine and made kit-generic: the app supplies the
+ * anchors + catalog + copy, the kit owns the animation/measure/queue mechanics.
+ * Dependency-free on purpose so the type surface can be imported anywhere.
+ */
+/** The animated hand/gesture shown over or beside a highlighted target. */
+type GestureKind = "swipe_up" | "swipe_down" | "swipe_left" | "swipe_right" | "tap" | "double_tap" | "pinch" | "zoom" | "none";
+/** Which side of the highlighted target the tooltip pill sits on. */
+type Placement = "top" | "bottom" | "left" | "right" | "center";
+/** A measured on-screen rectangle (window coordinates from measureInWindow). */
+interface TargetRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
+ * "seen?" gate must resolve during render with no async flash (otherwise a ring
+ * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
+ * is deliberately separate from the async `WireOnboardingStorage` used for
+ * session persistence.
+ */
+interface CoachmarkStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * One step in a guided tour. `anchorId` is looked up in the anchor registry at
+ * fire time; omit it for a centered, target-less hint (e.g. a scroll gesture).
+ * `id` doubles as the analytics name for the step.
+ */
+interface CoachmarkStep {
+    id: string;
+    message: string;
+    gesture?: GestureKind;
+    placement?: Placement;
+    anchorId?: string;
+    /** Extra action when the step is engaged (e.g. navigate to another tab). */
+    onEngage?: () => void;
+}
+
+export type { CoachmarkStorage as C, GestureKind as G, Placement as P, TargetRect as T, CoachmarkStep as a };

package/llms.txt

@@ -0,0 +1,36 @@
+# wireai-onboarding
+
+> A drop-in AI onboarding kit for React Native / Expo. One component, `<WireOnboarding>`, runs an
+> entire backend-orchestrated, AI-driven onboarding flow (themed cards, progress bar, a mid-flow
+> value screen, per-step validation, completion recap). It sits on top of the open-source
+> [`wireai-rn`](https://github.com/chohra-med/wireai-rn) SDK and talks to a multi-tenant Wire AI
+> backend over A2A. MIT licensed.
+
+## What an agent needs to know
+
+- **Install:** `npm install wireai-onboarding wireai-rn` (react + react-native are peers).
+- **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `wireai-onboarding/metro` — pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
+- **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
+- **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
+- **Capture is deterministic** — `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
+- **It can never break onboarding** — pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
+
+## Helpers (the reusable substrate)
+
+- `wireConfigFromEnv({ appId, metadata? })` → config or null (reads `EXPO_PUBLIC_WIREAI_API_KEY`/`_SERVER_URL`/`_APP_ID`).
+- `isOnboardingEnabled({ remote? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in.
+- `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)` → canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
+- `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
+- `reportClientEvent` / `makeSessionId` → report device-only funnel events to `POST /v1/events`. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
+- `deriveAnswers(messages)`, `themeFromBrand({ primary })`, `defaultIllustrations`, `DemoOnboarding` (dev/QA, no account).
+
+## Files
+
+- [README.md](./README.md): full usage, props table, theming, distribution.
+- [INTEGRATION_PROMPT.md](./INTEGRATION_PROMPT.md): a copy-paste prompt to make an AI agent (Claude Code) integrate this into an RN/Expo app end to end.
+- [AGENTS.md](./AGENTS.md): the ordered integration brief for agents.
+- [CHANGELOG.md](./CHANGELOG.md): version history.
+
+## Fastest path
+
+Run the `wire-rn-integration` Claude skill — it detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.

package/metro/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Type declarations for the `wireai-onboarding/metro` helper. This module runs in
+ * Node inside metro.config.js, so the config is loosely typed (`any`-ish) to avoid
+ * coupling to a specific Metro/Expo version.
+ */
+
+export interface WithWireOnboardingOptions {
+  /**
+   * The app dir whose `node_modules` the single-instance deps
+   * (react / react-native / wireai-rn / zod) resolve against. Default: process.cwd().
+   */
+  appRoot?: string;
+  /**
+   * Absolute path to the kit's `src/` dir. When set, the `wireai-onboarding`
+   * specifier maps here (source consumption) and the dir is added to watchFolders.
+   * When omitted, the kit resolves from the installed package.
+   */
+  source?: string;
+}
+
+/**
+ * Non-destructively wire the wireai-onboarding kit into an existing Metro config:
+ * pins single-instance deps to the app's copy, optionally maps the kit specifier
+ * to source + watches it. Mutates and returns the same config object.
+ */
+export function withWireOnboarding<TConfig extends Record<string, any>>(
+  config: TConfig,
+  options?: WithWireOnboardingOptions,
+): TConfig;
+
+/** The deps pinned to the app's single copy. */
+export const SINGLE_INSTANCE_DEPS: readonly ['react', 'react-native', 'wireai-rn', 'zod'];

package/metro/index.js

@@ -0,0 +1,83 @@
+/**
+ * withWireOnboarding — one-call Metro wiring for the wireai-onboarding kit.
+ *
+ * This file runs in Node inside your app's `metro.config.js` (it is NOT React
+ * Native code), so it's plain CommonJS with zero RN imports.
+ *
+ * It folds the ~25-line hand-written block (pin single-instance deps + map the
+ * kit specifier + watch source) into one non-destructive wrapper around your
+ * existing Metro config object.
+ *
+ *   // External app (kit installed from git/tarball):
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   const { withWireOnboarding } = require('wireai-onboarding/metro');
+ *   module.exports = withWireOnboarding(getDefaultConfig(__dirname));
+ *
+ *   // Source consumer (monorepo app, kit resolved from its src/):
+ *   const path = require('path');
+ *   module.exports = withWireOnboarding(getDefaultConfig(__dirname), {
+ *     source: path.join(__dirname, '../../getwire_ai/wireai-onboarding/src'),
+ *   });
+ *
+ * @param {object} config  An existing Metro config object (e.g. from getDefaultConfig).
+ * @param {object} [options]
+ * @param {string} [options.appRoot=process.cwd()]  The app dir whose node_modules
+ *   the single-instance deps (react/react-native/wireai-rn/zod) resolve against.
+ * @param {string} [options.source]  Absolute path to the kit's `src/` dir. When
+ *   set, the kit specifier maps here (source consumption) and it's added to
+ *   watchFolders; when omitted, the kit resolves from the installed package.
+ * @returns {object} The same config object, mutated in place and returned.
+ */
+'use strict';
+
+const path = require('path');
+
+/** Deps that MUST resolve to the app's single copy (a 2nd React instance crashes RN). */
+const SINGLE_INSTANCE_DEPS = ['react', 'react-native', 'wireai-rn', 'zod'];
+
+function withWireOnboarding(config, options) {
+  const opts = options || {};
+  const appRoot = opts.appRoot || process.cwd();
+  const source = opts.source;
+
+  if (!config || typeof config !== 'object') {
+    throw new Error('withWireOnboarding(config): expected a Metro config object.');
+  }
+
+  const appNodeModules = path.resolve(appRoot, 'node_modules');
+
+  // ── extraNodeModules: pin single-instance deps + map the kit specifier ──────
+  const resolver = config.resolver || (config.resolver = {});
+  const existingExtra = resolver.extraNodeModules || {};
+
+  const pinned = {};
+  for (const dep of SINGLE_INSTANCE_DEPS) {
+    pinned[dep] = path.join(appNodeModules, dep);
+  }
+
+  // Source consumption maps the bare specifier to the kit src; otherwise leave it
+  // to the installed package (don't set it, so normal node_modules resolution wins).
+  const kitMapping = source ? { '@wireai/activation': source } : {};
+
+  // Helper defaults first, then the app's own explicit entries last so anything
+  // the app already set wins on conflict (non-destructive).
+  resolver.extraNodeModules = {
+    ...pinned,
+    ...kitMapping,
+    ...existingExtra,
+  };
+
+  // ── watchFolders: add the kit source so Metro reads + HMRs it ───────────────
+  if (source) {
+    const existingWatch = Array.isArray(config.watchFolders) ? config.watchFolders : [];
+    config.watchFolders = existingWatch.includes(source)
+      ? existingWatch
+      : [...existingWatch, source];
+  }
+
+  return config;
+}
+
+module.exports = { withWireOnboarding };
+module.exports.withWireOnboarding = withWireOnboarding;
+module.exports.SINGLE_INSTANCE_DEPS = SINGLE_INSTANCE_DEPS;

package/package.json

@@ -0,0 +1,171 @@
+{
+  "name": "@wireai/activation",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
+  "author": "Malik Chohra <malik@getwireai.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/chohra-med/wireai-onboarding#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chohra-med/wireai-onboarding.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chohra-med/wireai-onboarding/issues"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "onboarding",
+    "ai",
+    "generative-ui",
+    "wireai",
+    "wireai-rn",
+    "dynamic-onboarding"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "react-native": {
+        "types": "./dist/index.d.ts",
+        "default": "./src/index.ts"
+      },
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./coachmarks": {
+      "react-native": {
+        "types": "./dist/coachmarks/index.d.ts",
+        "default": "./src/coachmarks/index.ts"
+      },
+      "import": {
+        "types": "./dist/coachmarks/index.d.mts",
+        "default": "./dist/coachmarks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/coachmarks/index.d.ts",
+        "default": "./dist/coachmarks/index.js"
+      }
+    },
+    "./showcase": {
+      "react-native": {
+        "types": "./dist/showcase/index.d.ts",
+        "default": "./src/showcase/index.ts"
+      },
+      "import": {
+        "types": "./dist/showcase/index.d.mts",
+        "default": "./dist/showcase/index.mjs"
+      },
+      "require": {
+        "types": "./dist/showcase/index.d.ts",
+        "default": "./dist/showcase/index.js"
+      }
+    },
+    "./reviews": {
+      "react-native": {
+        "types": "./dist/reviews/index.d.ts",
+        "default": "./src/reviews/index.ts"
+      },
+      "import": {
+        "types": "./dist/reviews/index.d.mts",
+        "default": "./dist/reviews/index.mjs"
+      },
+      "require": {
+        "types": "./dist/reviews/index.d.ts",
+        "default": "./dist/reviews/index.js"
+      }
+    },
+    "./questionnaire": {
+      "react-native": {
+        "types": "./dist/questionnaire/index.d.ts",
+        "default": "./src/questionnaire/index.ts"
+      },
+      "import": {
+        "types": "./dist/questionnaire/index.d.mts",
+        "default": "./dist/questionnaire/index.mjs"
+      },
+      "require": {
+        "types": "./dist/questionnaire/index.d.ts",
+        "default": "./dist/questionnaire/index.js"
+      }
+    },
+    "./metro": {
+      "types": "./metro/index.d.ts",
+      "default": "./metro/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "metro",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "llms.txt",
+    "INTEGRATION_PROMPT.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"src/**/*.test.ts\" \"test/canary/**/*.test.tsx\"",
+    "pack:tarball": "npm pack"
+  },
+  "peerDependencies": {
+    "@blazejkustra/react-native-onboarding": ">=1",
+    "expo-blur": ">=13",
+    "expo-store-review": ">=6",
+    "react": ">=18.0.0",
+    "react-native": ">=0.73.0",
+    "react-native-reanimated": ">=3",
+    "react-native-safe-area-context": ">=4.0.0",
+    "wireai-rn": ">=0.2.3",
+    "zod": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": false
+    },
+    "react-native-reanimated": {
+      "optional": true
+    },
+    "expo-blur": {
+      "optional": true
+    },
+    "expo-store-review": {
+      "optional": true
+    },
+    "@blazejkustra/react-native-onboarding": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@blazejkustra/react-native-onboarding": "^1.0.1",
+    "@types/react": "^19.0.0",
+    "expo-blur": "^15.0.0",
+    "react": "^19.2.7",
+    "react-native": "^0.86.0",
+    "react-native-reanimated": "^4.1.1",
+    "react-native-safe-area-context": "^4.14.1",
+    "react-test-renderer": "^19.2.7",
+    "sucrase": "^3.35.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/DemoOnboarding.tsx

@@ -0,0 +1,133 @@
+/**
+ * DemoOnboarding — a drop-in dev/QA trigger that runs the onboarding flow ON
+ * DEMAND in a modal, then closes. No loop, no account, no navigation side-effects:
+ * re-runnable infinitely with the same logged-in user. Place it anywhere a host
+ * wants (e.g. a __DEV__ row in Settings). If `config` is null (the app hasn't
+ * integrated Wire AI yet), it shows a hint instead of the flow.
+ *
+ *   {__DEV__ && (
+ *     <DemoOnboarding config={wireConfigFromEnv({ appId: "my-app" })} theme={myTheme} />
+ *   )}
+ *
+ * It does NOT persist by default (a demo, not a real run) — pass `onComplete` if
+ * you want to observe the captured answers.
+ */
+import { useCallback, useMemo, useState, type ReactNode } from "react";
+import { Modal, Pressable, StyleSheet, Text, View } from "react-native";
+
+import { WireOnboarding } from "./WireOnboarding";
+import { mergeTheme } from "./theme/defaultTheme";
+import type { OnboardingTheme } from "./theme/types";
+import type { OnboardingResult, WireOnboardingConfig, WireOnboardingProps } from "./types";
+
+export type DemoOnboardingProps = {
+  /** The Wire AI config, or `null` when the app hasn't integrated Wire AI yet. */
+  config: WireOnboardingConfig | null;
+  theme?: WireOnboardingProps["theme"];
+  illustrations?: WireOnboardingProps["illustrations"];
+  validators?: WireOnboardingProps["validators"];
+  copy?: WireOnboardingProps["copy"];
+  /** Trigger button label. Default "Demo onboarding". */
+  label?: string;
+  /** Observe the demo result. By default the demo just closes (no persistence). */
+  onComplete?: (result: OnboardingResult) => void;
+  /** Render your own trigger instead of the default button: `(open) => <YourButton onPress={open} />`. */
+  renderTrigger?: (open: () => void) => ReactNode;
+};
+
+export function DemoOnboarding({
+  config,
+  theme,
+  illustrations,
+  validators,
+  copy,
+  label = "Demo onboarding",
+  onComplete,
+  renderTrigger,
+}: DemoOnboardingProps) {
+  const [open, setOpen] = useState(false);
+  const [runId, setRunId] = useState(0);
+  const t = useMemo(() => mergeTheme(theme ?? {}), [theme]);
+  const styles = useMemo(() => makeStyles(t), [t]);
+
+  const openDemo = useCallback(() => {
+    setRunId((n) => n + 1); // remount WireOnboarding → a fresh A2A session each open
+    setOpen(true);
+  }, []);
+  const close = useCallback(() => setOpen(false), []);
+  const finish = useCallback(
+    (result: OnboardingResult) => {
+      onComplete?.(result);
+      setOpen(false);
+    },
+    [onComplete],
+  );
+
+  return (
+    <>
+      {renderTrigger ? (
+        renderTrigger(openDemo)
+      ) : (
+        <Pressable onPress={openDemo} style={styles.trigger} accessibilityRole="button">
+          <Text style={styles.triggerText}>{label}</Text>
+        </Pressable>
+      )}
+
+      <Modal
+        visible={open}
+        animationType="slide"
+        presentationStyle="fullScreen"
+        onRequestClose={close}
+      >
+        <View style={styles.modal}>
+          {config ? (
+            <WireOnboarding
+              key={runId}
+              config={config}
+              theme={theme}
+              illustrations={illustrations}
+              validators={validators}
+              copy={copy}
+              onComplete={finish}
+              onSkip={close}
+              onError={close}
+            />
+          ) : (
+            <View style={styles.notice}>
+              <Text style={styles.noticeTitle}>Wire AI not configured</Text>
+              <Text style={styles.noticeBody}>
+                Set the Wire AI key + server URL (e.g. via wireConfigFromEnv) to demo the AI
+                onboarding here.
+              </Text>
+              <Pressable onPress={close} style={styles.trigger} accessibilityRole="button">
+                <Text style={styles.triggerText}>Close</Text>
+              </Pressable>
+            </View>
+          )}
+        </View>
+      </Modal>
+    </>
+  );
+}
+
+function makeStyles(t: OnboardingTheme) {
+  return StyleSheet.create({
+    trigger: {
+      backgroundColor: t.colors.primary,
+      borderRadius: t.button.radius,
+      paddingVertical: 14,
+      paddingHorizontal: 20,
+      alignItems: "center",
+    },
+    triggerText: { color: t.colors.onPrimary, fontFamily: t.fonts.medium, fontSize: 16 },
+    modal: { flex: 1, backgroundColor: t.colors.background },
+    notice: { flex: 1, alignItems: "center", justifyContent: "center", padding: 24, gap: 12 },
+    noticeTitle: { color: t.colors.text, fontFamily: t.fonts.bold, fontSize: 20 },
+    noticeBody: {
+      color: t.colors.textMuted,
+      fontFamily: t.fonts.regular,
+      fontSize: 15,
+      textAlign: "center",
+    },
+  });
+}