aimeat 2.7.0 → 3.1.0

package/dist/src/services/onboarding-funnel.d.ts

@@ -0,0 +1,240 @@
+/**
+ * @file src/services/onboarding-funnel.ts
+ * @description The MCP onboarding funnel made observable (UX-remake v3, P3). The connector step
+ *   happens inside the user's AI tool where this node cannot see it, so the node records the two
+ *   ends it CAN see — the hello page being opened, and the first MCP session actually arriving —
+ *   and runs one rescue: an account that is a day old with no MCP call yet gets a single email
+ *   with the direct link and the tier checklist (the page itself names tier limits as the most
+ *   common failure). Markers are memory records in the owner's GHII namespace (memory-contracts:
+ *   extend the memory system, not the schema), so the funnel is queryable without a new table
+ *   and visible to the owner in their own Memory tab.
+ * @structure
+ *   - FIRST_MCP_CALL_KEY / HELLO_PAGE_OPENED_KEY / ACTIVATED_KEY / MCP_RESCUE_SENT_KEY: marker keys
+ *   - ONBOARDING_KEYS: every remake event key, in ONE place (05-mittaus.md) — nothing that writes
+ *     a funnel marker spells a key literal of its own
+ *   - recordFirstMcpCall() / recordHelloPageOpened() / recordActivation(): write-once markers
+ *   - recordTrack() / recordTrackSwitch(): which path the account was created on, and how many
+ *     times it flipped. The switch NEVER rewrites `track` — see the note on recordTrackSwitch.
+ *   - recordOnboardingEvent(): the generic write-once marker every remake phase writes through
+ *   - recordWelcomeMatPasted(): the ONE deliberately non-write-once marker (attempts accumulate)
+ *   - readOnboardingFunnel(): the operator view's rows (activation, TTFV, rescue, remake events)
+ *   - runMcpOnboardingRescueJob(): the scheduled rescue pass (core handler 'mcp-onboarding-rescue')
+ * @usage
+ *   import { recordFirstMcpCall } from '../services/onboarding-funnel.js';
+ *   void recordFirstMcpCall(storage, config, owner, platform);   // fire-and-forget at MCP init
+ * @version-history
+ *   v1.2.0 — 2026-08-07 — REMAKE phase 0: onboarding.track (legacy|remake + switched) written at
+ *     account creation, the six remake event keys + the agent-door pair collected into
+ *     ONBOARDING_KEYS, generic write-once + attempts-accumulating writers, and readOnboardingFunnel
+ *     rewritten onto ONE listMemoryForOwners query (was 4 getMemory per account) now that it reads
+ *     eleven markers instead of four.
+ *   v1.1.0 — 2026-08-07 — Activation marker + readOnboardingFunnel(): the account's first durable
+ *     own output (app / workspace / agent write) as ONE event with a kind, so an activation rate
+ *     and TTFV are computable (05-mittaus.md).
+ *   v1.0.0 — 2026-08-07 — Initial (UX-remake v3, block 1.6).
+ */
+import type { AimeatConfig } from '../config.js';
+import type { Storage } from '../storage/interface.js';
+/** Written once, when the owner's first authenticated MCP session initializes. */
+export declare const FIRST_MCP_CALL_KEY = "onboarding.first_mcp_call";
+/** Written once, when a signed-in owner first opens the Hello MCP guidance. */
+export declare const HELLO_PAGE_OPENED_KEY = "onboarding.hello_page_opened";
+/** Written once, when the rescue email for a silent account has been sent (or attempted). */
+export declare const MCP_RESCUE_SENT_KEY = "onboarding.mcp_rescue_sent";
+/**
+ * The ACTIVATION marker (05-mittaus.md): the first time this account produced a durable thing of
+ * its own — a published app, a published workspace item, or an agent's first write. One event with
+ * a `kind` dimension rather than three, so one activation rate is comparable across the personas.
+ * Written once; the value records which of the three came first and when.
+ */
+export declare const ACTIVATED_KEY = "onboarding.activated";
+export type ActivationKind = 'app' | 'workspace' | 'agent';
+/**
+ * EVERY remake funnel key, in one place (05-mittaus.md). Nothing outside this module spells one of
+ * these strings: a key typed twice is a marker that silently stops being counted the day one of
+ * the two is edited, and a funnel that undercounts reads as a product that does not work.
+ */
+export declare const ONBOARDING_KEYS: {
+    /** Which path the account was created on. Written ONCE at account creation. */
+    readonly track: "onboarding.track";
+    /** The welcome mat paste. The ONE non-write-once marker: attempts accumulate. */
+    readonly welcomeMatPasted: "onboarding.welcome_mat_pasted";
+    /** What the model claimed about itself, or what the person answered when asked. */
+    readonly aiModelDetected: "onboarding.ai_model_detected";
+    /** A = MCP-capable client, B = needs a better one first, agent = the front-page agent door. */
+    readonly branchTaken: "onboarding.branch_taken";
+    readonly firstAgentConnected: "onboarding.first_agent_connected";
+    readonly homeInitialized: "onboarding.home_initialized";
+    /** The FIRST of the four rooms entered. Later ones do not overwrite it. */
+    readonly roomEntered: "onboarding.room_entered";
+    /** Agent door (12-ai-rekisteroi.md): the POST landed and the mail went out. */
+    readonly inviteSentByAgent: "onboarding.invite_sent_by_agent";
+    readonly inviteCompleted: "onboarding.invite_completed";
+    /** Durable mark on the account: an agent started this, with which model. */
+    readonly startedByAgent: "onboarding.started_by_agent";
+    readonly agentDoorStarted: "onboarding.agent_door_started";
+    readonly agentDoorResult: "onboarding.agent_door_result";
+    /**
+     * The friendly nudge to an account nobody has seen for a fortnight. Accumulating, not
+     * write-once: someone can go quiet more than once in a lifetime, and a write-once marker would
+     * mean the second silence is never noticed. `sentAt` carries the last send, which is what the
+     * cooldown is measured from.
+     */
+    readonly inactivityNudge: "onboarding.inactivity_nudge";
+};
+/** Which onboarding path an account was created on. Cohorts are meaningless without it. */
+export type OnboardingTrack = 'legacy' | 'remake';
+export type OnboardingBranch = 'A' | 'B' | 'agent';
+export type OnboardingRoom = 'create' | 'organise' | 'monetise' | 'company' | 'messages';
+/** K3: new accounts land on the remake; existing ones stay legacy until they switch themselves. */
+export declare const DEFAULT_TRACK: OnboardingTrack;
+/**
+ * Accounts created before this feature existed are never rescued — a months-old account
+ * suddenly getting "you have not connected your AI yet" would read as a data leak, not help.
+ */
+export declare const RESCUE_FEATURE_EPOCH = "2026-08-07T00:00:00Z";
+/**
+ * Write a marker key once; returns false when it already existed.
+ *
+ * Exported so a sibling job (the inactivity nudge) uses THIS implementation rather than a
+ * second copy: the ttlHours:null matters — a marker with a TTL is swept by the memory cleanup
+ * job, and an idempotency marker that expires turns a one-off email into a recurring one.
+ */
+export declare function writeMarkerOnce(storage: Storage, ownerGaii: string, key: string, value: Record<string, unknown>): Promise<boolean>;
+/**
+ * Record the owner's FIRST authenticated MCP session. Called from the MCP initialize path;
+ * failures are logged, never thrown — funnel bookkeeping must not break a working connection.
+ */
+export declare function recordFirstMcpCall(storage: Storage, config: AimeatConfig, owner: string, client?: string): Promise<void>;
+/** Record that a signed-in owner opened the Hello MCP guidance. Same never-throw contract. */
+export declare function recordHelloPageOpened(storage: Storage, config: AimeatConfig, owner: string): Promise<void>;
+/**
+ * Record the account's ACTIVATION — its first durable own output. Fire-and-forget from whichever
+ * path produced the thing (app publish, workspace publish, agent write); the marker is write-once,
+ * so the first caller wins and later ones are a no-op. Never throws: an activation marker must
+ * never be able to fail the publish it is measuring.
+ */
+export declare function recordActivation(storage: Storage, config: AimeatConfig, owner: string, kind: ActivationKind): Promise<void>;
+/**
+ * Record which path this account was created on. Called from BOTH account-creation routes
+ * (POST /v1/ghii and POST /v1/owners) so no door leaves an account without a track — an untracked
+ * account is invisible to one half of the funnel and inflates neither, which is worse than either.
+ * Write-once: re-registration in dev/test mode must not relabel an existing cohort.
+ */
+export declare function recordTrack(storage: Storage, config: AimeatConfig, owner: string, track?: OnboardingTrack): Promise<void>;
+/**
+ * The switch between the new home and the old profile. Increments `switched` and leaves `track`
+ * exactly as it was: rewriting it would move the account between cohorts every time the person
+ * flipped, and a cohort whose membership changes under you measures nothing. The counter is
+ * itself a result — remake-created accounts switching away is the signal the remake failed.
+ */
+export declare function recordTrackSwitch(storage: Storage, config: AimeatConfig, owner: string): Promise<number>;
+/** Read an account's track (and switch count). Absent marker = an account older than the feature. */
+export declare function readTrack(storage: Storage, config: AimeatConfig, owner: string): Promise<{
+    track: OnboardingTrack;
+    switched: number;
+}>;
+/**
+ * The generic write-once remake marker. Every phase writes through this rather than reaching for
+ * storage directly, so all of them share the same never-throw contract: funnel bookkeeping must
+ * never be able to fail the thing it is measuring. Returns whether this call was the one that wrote.
+ */
+export declare function recordOnboardingEvent(storage: Storage, config: AimeatConfig, owner: string, key: typeof ONBOARDING_KEYS[keyof typeof ONBOARDING_KEYS], value: Record<string, unknown>): Promise<boolean>;
+/** What we know about the person's AI, and how we came to know it. */
+export interface AiDetection {
+    model: string | null;
+    vendor: string | null;
+    client: string | null;
+    mcp: 'yes' | 'no' | 'unknown';
+    /** 'meta' = read off the pasted page; 'asked' = the person answered. */
+    source: 'meta' | 'asked';
+    /** An app name that matched nothing — the list the alias map grows from. */
+    unknownClient?: string | null;
+    resolvedClient?: string | null;
+    /**
+     * The person's answer to the paid-tier question, when their app needs one. Kept because the
+     * live "are they still blocked?" question has to be RECOMPUTED from what is known, and without
+     * this the recomputation would re-ask a question they already answered.
+     */
+    hasPaidPlan?: boolean | null;
+    /**
+     * A FRESH welcome mat, which replaces the record outright rather than deferring to whatever
+     * was there. See the ordering note on recordAiModelDetected.
+     */
+    supersedes?: boolean;
+}
+/**
+ * Record what the person's AI is. One record, not an append log — but NOT plain write-once,
+ * because the two sources are not equal evidence.
+ *
+ * A model's claim about its own app is unreliable by nature (04-mcp-kyvykkyys.md); the person's
+ * own answer is not. So an `asked` reading replaces a `meta` one, and nothing replaces an `asked`
+ * one. Under strict write-once the `source` field would be decoration: the page's guess would be
+ * frozen in the funnel even after the person corrected it, and every later read would be of the
+ * less reliable of the two answers we had.
+ */
+export declare function recordAiModelDetected(storage: Storage, config: AimeatConfig, owner: string, detection: AiDetection): Promise<void>;
+/**
+ * The welcome-mat paste — the one marker that is NOT write-once. `attempts` accumulates because
+ * how many tries the mat took is the direct measure of the prompt's quality (03-welcome-mat.md),
+ * and a write-once marker would report every account as a first-try success. `result` holds the
+ * LATEST outcome, so ok-after-three-failures reads as ok with attempts=4.
+ * There is no `skipped` value and no caller that could produce one: the mat cannot be skipped.
+ */
+export declare function recordWelcomeMatPasted(storage: Storage, config: AimeatConfig, owner: string, result: 'ok' | 'failed'): Promise<{
+    attempts: number;
+}>;
+/** One account's funnel state, as the operator view reads it. */
+export interface FunnelRow {
+    owner: string;
+    ghii: string;
+    createdAt: string;
+    locale: string;
+    helloOpenedAt: string | null;
+    firstMcpCallAt: string | null;
+    mcpClient: string | null;
+    activatedAt: string | null;
+    activationKind: ActivationKind | null;
+    /** Signup → activation, in minutes. Null until activated. */
+    ttfvMinutes: number | null;
+    rescueSentAt: string | null;
+    /** Which path the account was created on. `legacy` also covers pre-feature accounts. */
+    track: OnboardingTrack;
+    /** How many times the person flipped between the two. Never changes `track`. */
+    switched: number;
+    matResult: 'ok' | 'failed' | null;
+    matAttempts: number;
+    /** The model's own claim about itself — unreliable by nature, kept for exactly that reason. */
+    aiModel: string | null;
+    /** The deciding field: MCP is a property of the CLIENT APP, not the model. */
+    aiClient: string | null;
+    aiMcp: 'yes' | 'no' | 'unknown' | null;
+    /** 'meta' = read off the page; 'asked' = the person answered. 'asked' is the trustworthy one. */
+    aiSource: 'meta' | 'asked' | null;
+    branch: OnboardingBranch | null;
+    firstAgentConnectedAt: string | null;
+    homeInitializedAt: string | null;
+    /** The FIRST room entered — which of the four the person wanted, not where they ended up. */
+    room: OnboardingRoom | null;
+}
+/**
+ * The whole funnel as rows, newest account first — the operator surface (05-mittaus.md) and the
+ * only place these markers are read together. Test accounts (uxtest-*) are excluded here rather
+ * than at write time, so a re-run measures itself but never pollutes the operator's numbers.
+ */
+export declare function readOnboardingFunnel(storage: Storage, opts?: {
+    since?: string;
+    limit?: number;
+}): Promise<FunnelRow[]>;
+/**
+ * The rescue pass. For each account created after the feature epoch, older than a day and
+ * younger than a week, with a VERIFIED email, no MCP session seen and no rescue sent: send one
+ * email and mark it sent. Runs as core handler 'mcp-onboarding-rescue'.
+ */
+export declare function runMcpOnboardingRescueJob(config: AimeatConfig, storage: Storage, 
+/** Test seam: freeze the clock and the epoch. Production callers pass nothing. */
+opts?: {
+    now?: number;
+    epoch?: number;
+}): Promise<void>;
+//# sourceMappingURL=onboarding-funnel.d.ts.map

package/dist/src/services/onboarding-funnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-funnel.d.ts","sourceRoot":"","sources":["../../../src/services/onboarding-funnel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAKvD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AACpE,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAChE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,yBAAyB,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,WAAW,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,eAAe;IACxB,+EAA+E;;IAE/E,iFAAiF;;IAEjF,mFAAmF;;IAEnF,+FAA+F;;;;IAI/F,2EAA2E;;IAE3E,+EAA+E;;;IAG/E,4EAA4E;;;;IAI5E;;;;;OAKG;;CAEG,CAAC;AAEX,2FAA2F;AAC3F,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,gBAAgB,GAAG,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC;AAGnD,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AACzF,mGAAmG;AACnG,eAAO,MAAM,aAAa,EAAE,eAA0B,CAAC;AAEvD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAM3D;;;;;;GAMG;AACH,wBAAsB,eAAe,CACjC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjF,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAMD;;;GAGG;AACH,wBAAsB,kBAAkB,CACpC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GACvE,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,8FAA8F;AAC9F,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GACtD,OAAO,CAAC,IAAI,CAAC,CAWf;AAKD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAClC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAC5E,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC7B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,eAA+B,GAC9F,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACnC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GACtD,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED,qGAAqG;AACrG,wBAAsB,SAAS,CAC3B,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GACtD,OAAO,CAAC;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAIvD;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EACrD,GAAG,EAAE,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,EACzD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,OAAO,CAAC,CAUlB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,GAAG,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAC9B,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC7B;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,GAC9E,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CACxC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAG,QAAQ,GAC/E,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB/B;AAED,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,wFAAwF;IACxF,KAAK,EAAE,eAAe,CAAC;IACvB,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,IAAI,GAAG,QAAQ,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,+FAA+F;IAC/F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,iGAAiG;IACjG,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,6FAA6F;IAC7F,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChE,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;AA0GD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC3C,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,OAAO;AAChB,kFAAkF;AAClF,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,OAAO,CAAC,IAAI,CAAC,CA+Df"}