@pear-protocol/agent-sdk 0.4.1 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ TypeScript client for the Pear **agent chat** API — the conversational assista
 (pair-trade ideas, market data, and confirm-before-write trade execution).
 
 - **`@pear-protocol/agent-sdk`** — framework-agnostic core (`AgentChatClient`).
-- **`@pear-protocol/agent-sdk/react`** — optional React hooks (`useAgentChat`, `useAgentSessions`).
+- **`@pear-protocol/agent-sdk/react`** — optional React hooks (`useAgentChat`, `useAgentSessions`, `useWalletLink`, `useOnboarding`).
 
 Published to **public npm** (same registry as the org's other `@pear-protocol`
 packages — no `.npmrc` or token needed). The wire types are a single source of
@@ -116,6 +116,66 @@ React apps can use `useWalletLink(client)` from `./react` —
 `{ linked, isWorking, error, link, unlink, refresh }` (`linked` is `null`
 while the initial status fetch is in flight).
 
+## Onboarding (deterministic, FE-controlled)
+
+A first-time user can be onboarded with a short, deterministic wizard you render
+yourself — the agent exposes the flow over REST (no in-band chat short-circuit).
+Every endpoint returns the **same** state shape so you drive the loop off one type:
+
+```ts
+let state = await client.getOnboardingState("pear_v3"); // { needsOnboarding, nextQuestion, isLast, answered, total, onboardingState, profile }
+while (state.needsOnboarding && state.nextQuestion) {
+  const q = state.nextQuestion;
+  // closed questions carry q.options: { value, label, description? } — render
+  // label + description, submit value. Free-text note uses the typed string.
+  const value = q.freeform ? userTypedText : userPickedOption.value;
+  state = await client.submitOnboardingAnswer("pear_v3", { questionId: q.id, value });
+}
+// or bail: await client.skipOnboarding("pear_v3");  // smart-skip (parity with TG)
+// start over:  await client.resetOnboarding();      // clears picks — NOT for edits
+// surface-static question set:  await client.getOnboardingQuestions("pear_v3");
+```
+
+### Editing preferences (pre-fill + non-destructive)
+
+`getOnboardingState` returns `profile` — the caller's CURRENT picks
+(`experience`/`tradingStyle`/`riskAppetite`/`favoriteSectors`/`avoidAssets`/`note`,
+all optional; `{}` for a new user). Render an edit form from the full question set
++ `profile`, then submit only the changed field — the server MERGES, so editing
+one field never wipes the others. **Use `submitOnboardingAnswer` to edit; `resetOnboarding`
+is "start over" only.**
+
+```ts
+const [state, questions] = await Promise.all([
+  client.getOnboardingState("pear_v3"),
+  client.getOnboardingQuestions("pear_v3"),
+]);
+// Render each question PRE-FILLED: e.g. select state.profile.tradingStyle.
+// On a change, submit just that field (non-destructive merge):
+await client.submitOnboardingAnswer("pear_v3", { questionId: "risk_appetite", value: "aggressive" });
+```
+
+React apps can use `useOnboarding({ client, surface })` from `./react` —
+`{ needsOnboarding, onboardingState, currentQuestion, questions, profile, isLast, progress, submitAnswer, skip, reset, loading, error, refresh }`.
+Gate your wizard on `needsOnboarding` once `loading` is false; for editing, render
+`questions` pre-filled from `profile` and call `submitAnswer(questionId, value)`:
+
+```tsx
+function App({ client }) {
+  const ob = useOnboarding({ client, surface: "pear_v3" });
+  if (ob.loading) return <Spinner />;
+  // First run — sequential wizard off currentQuestion + progress.
+  if (ob.needsOnboarding) return <OnboardingWizard {...ob} />;
+  // Edit — pre-fill from ob.profile, submit changed fields (no reset):
+  // ob.questions.map(q => …current value = ob.profile[…]…
+  //   onChange={(value) => ob.submitAnswer(q.id, value)} )
+  return <Chat client={client} />;
+}
+```
+
+`submitAnswer` is overloaded: `submitAnswer(value)` answers the next first-run
+question; `submitAnswer(questionId, value)` edits a specific field.
+
 ## Trade tickets (confirm-before-write)
 
 A turn that would move money returns a `pendingAction`

package/dist/{client-BSUkCr7k.d.cts → client-ETT3B7Kt.d.cts}

@@ -220,6 +220,122 @@ declare const AgentChatMessageSchema: z.ZodObject<{
 }, z.core.$loose>;
 type AgentChatMessage = z.infer<typeof AgentChatMessageSchema>;
 
+declare const OnboardingQuestionIdSchema: z.ZodEnum<{
+    experience: "experience";
+    trading_style: "trading_style";
+    risk_appetite: "risk_appetite";
+    note: "note";
+}>;
+type OnboardingQuestionId = z.infer<typeof OnboardingQuestionIdSchema>;
+declare const OnboardingStateSchema: z.ZodEnum<{
+    not_started: "not_started";
+    skipped: "skipped";
+    completed: "completed";
+}>;
+type OnboardingState = z.infer<typeof OnboardingStateSchema>;
+declare const OnboardingOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OnboardingOption = z.infer<typeof OnboardingOptionSchema>;
+declare const OnboardingQuestionSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        experience: "experience";
+        trading_style: "trading_style";
+        risk_appetite: "risk_appetite";
+        note: "note";
+    }>;
+    prompt: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    freeform: z.ZodBoolean;
+}, z.core.$strip>;
+type OnboardingQuestion = z.infer<typeof OnboardingQuestionSchema>;
+declare const OnboardingProfileSchema: z.ZodObject<{
+    experience: z.ZodOptional<z.ZodEnum<{
+        new: "new";
+        intermediate: "intermediate";
+        seasoned: "seasoned";
+    }>>;
+    tradingStyle: z.ZodOptional<z.ZodEnum<{
+        scalper: "scalper";
+        swing: "swing";
+        position: "position";
+        passive: "passive";
+    }>>;
+    riskAppetite: z.ZodOptional<z.ZodEnum<{
+        conservative: "conservative";
+        balanced: "balanced";
+        aggressive: "aggressive";
+    }>>;
+    favoriteSectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    avoidAssets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OnboardingProfile = z.infer<typeof OnboardingProfileSchema>;
+declare const OnboardingStateResponseSchema: z.ZodObject<{
+    needsOnboarding: z.ZodBoolean;
+    onboardingState: z.ZodEnum<{
+        not_started: "not_started";
+        skipped: "skipped";
+        completed: "completed";
+    }>;
+    nextQuestion: z.ZodNullable<z.ZodObject<{
+        id: z.ZodEnum<{
+            experience: "experience";
+            trading_style: "trading_style";
+            risk_appetite: "risk_appetite";
+            note: "note";
+        }>;
+        prompt: z.ZodString;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        freeform: z.ZodBoolean;
+    }, z.core.$strip>>;
+    isLast: z.ZodBoolean;
+    answered: z.ZodNumber;
+    total: z.ZodNumber;
+    profile: z.ZodObject<{
+        experience: z.ZodOptional<z.ZodEnum<{
+            new: "new";
+            intermediate: "intermediate";
+            seasoned: "seasoned";
+        }>>;
+        tradingStyle: z.ZodOptional<z.ZodEnum<{
+            scalper: "scalper";
+            swing: "swing";
+            position: "position";
+            passive: "passive";
+        }>>;
+        riskAppetite: z.ZodOptional<z.ZodEnum<{
+            conservative: "conservative";
+            balanced: "balanced";
+            aggressive: "aggressive";
+        }>>;
+        favoriteSectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        avoidAssets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type OnboardingStateResponse = z.infer<typeof OnboardingStateResponseSchema>;
+declare const OnboardingAnswerRequestSchema: z.ZodObject<{
+    questionId: z.ZodEnum<{
+        experience: "experience";
+        trading_style: "trading_style";
+        risk_appetite: "risk_appetite";
+        note: "note";
+    }>;
+    value: z.ZodString;
+}, z.core.$strip>;
+type OnboardingAnswerRequest = z.infer<typeof OnboardingAnswerRequestSchema>;
+
 declare const TradeLinkSchema: z.ZodObject<{
     link: z.ZodString;
     platform: z.ZodString;
@@ -375,6 +491,11 @@ declare class AgentChatClient {
         code?: string;
     }): Promise<SelfLinkResult>;
     unlinkWallet(): Promise<SelfUnlinkResult>;
+    getOnboardingState(surface: ChatSurface): Promise<OnboardingStateResponse>;
+    getOnboardingQuestions(surface: ChatSurface): Promise<OnboardingQuestion[]>;
+    submitOnboardingAnswer(surface: ChatSurface, body: OnboardingAnswerRequest): Promise<OnboardingStateResponse>;
+    skipOnboarding(surface: ChatSurface): Promise<OnboardingStateResponse>;
+    resetOnboarding(): Promise<OnboardingStateResponse>;
 }
 
-export { type TwitterSource as $, AgentChatClient as A, type SessionSummary as B, type CancelResult as C, SessionSummarySchema as D, ErrorEventSchema as E, type SetConfirmationsResult as F, SetConfirmationsResultSchema as G, type SetExecutionResult as H, SetExecutionResultSchema as I, SourcesEventSchema as J, StatusEventSchema as K, type LinkStatus as L, type StreamEvent as M, type SuggestedAction as N, SuggestedActionSchema as O, type PendingAction as P, type TicketAction as Q, TicketActionSchema as R, type SelfLinkResult as S, ThinkingEventSchema as T, type TicketStatus as U, TicketStatusSchema as V, TokenEventSchema as W, type TradeLink as X, TradeLinkSchema as Y, type TradeSettings as Z, TradeSettingsSchema as _, type AgentChatClientConfig as a, TwitterSourceSchema as a0, type AgentChatMessage as b, AgentChatMessageSchema as c, type AgentEvent as d, type AgentWireEvent as e, AgentWireEventSchema as f, CancelResultSchema as g, type ChatMode as h, ChatModeSchema as i, type ChatResult as j, ChatResultSchema as k, type ChatSurface as l, ChatSurfaceSchema as m, type CitationSource as n, CitationSourceSchema as o, type ConfirmResult as p, ConfirmResultSchema as q, LinkStatusSchema as r, PendingActionSchema as s, SelfLinkResultSchema as t, type SelfUnlinkResult as u, SelfUnlinkResultSchema as v, type Session as w, type SessionListItem as x, SessionListItemSchema as y, SessionSchema as z };
+export { StatusEventSchema as $, AgentChatClient as A, OnboardingQuestionSchema as B, type CancelResult as C, type OnboardingState as D, ErrorEventSchema as E, type OnboardingStateResponse as F, OnboardingStateResponseSchema as G, OnboardingStateSchema as H, PendingActionSchema as I, SelfLinkResultSchema as J, type SelfUnlinkResult as K, type LinkStatus as L, SelfUnlinkResultSchema as M, type Session as N, type OnboardingAnswerRequest as O, type PendingAction as P, type SessionListItem as Q, SessionListItemSchema as R, type SelfLinkResult as S, SessionSchema as T, type SessionSummary as U, SessionSummarySchema as V, type SetConfirmationsResult as W, SetConfirmationsResultSchema as X, type SetExecutionResult as Y, SetExecutionResultSchema as Z, SourcesEventSchema as _, type AgentChatClientConfig as a, type StreamEvent as a0, type SuggestedAction as a1, SuggestedActionSchema as a2, ThinkingEventSchema as a3, type TicketAction as a4, TicketActionSchema as a5, type TicketStatus as a6, TicketStatusSchema as a7, TokenEventSchema as a8, type TradeLink as a9, TradeLinkSchema as aa, type TradeSettings as ab, TradeSettingsSchema as ac, type TwitterSource as ad, TwitterSourceSchema as ae, type AgentChatMessage as b, AgentChatMessageSchema as c, type AgentEvent as d, type AgentWireEvent as e, AgentWireEventSchema as f, CancelResultSchema as g, type ChatMode as h, ChatModeSchema as i, type ChatResult as j, ChatResultSchema as k, type ChatSurface as l, ChatSurfaceSchema as m, type CitationSource as n, CitationSourceSchema as o, type ConfirmResult as p, ConfirmResultSchema as q, LinkStatusSchema as r, OnboardingAnswerRequestSchema as s, type OnboardingOption as t, OnboardingOptionSchema as u, type OnboardingProfile as v, OnboardingProfileSchema as w, type OnboardingQuestion as x, type OnboardingQuestionId as y, OnboardingQuestionIdSchema as z };

package/dist/{client-BSUkCr7k.d.ts → client-ETT3B7Kt.d.ts}

@@ -220,6 +220,122 @@ declare const AgentChatMessageSchema: z.ZodObject<{
 }, z.core.$loose>;
 type AgentChatMessage = z.infer<typeof AgentChatMessageSchema>;
 
+declare const OnboardingQuestionIdSchema: z.ZodEnum<{
+    experience: "experience";
+    trading_style: "trading_style";
+    risk_appetite: "risk_appetite";
+    note: "note";
+}>;
+type OnboardingQuestionId = z.infer<typeof OnboardingQuestionIdSchema>;
+declare const OnboardingStateSchema: z.ZodEnum<{
+    not_started: "not_started";
+    skipped: "skipped";
+    completed: "completed";
+}>;
+type OnboardingState = z.infer<typeof OnboardingStateSchema>;
+declare const OnboardingOptionSchema: z.ZodObject<{
+    value: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OnboardingOption = z.infer<typeof OnboardingOptionSchema>;
+declare const OnboardingQuestionSchema: z.ZodObject<{
+    id: z.ZodEnum<{
+        experience: "experience";
+        trading_style: "trading_style";
+        risk_appetite: "risk_appetite";
+        note: "note";
+    }>;
+    prompt: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    freeform: z.ZodBoolean;
+}, z.core.$strip>;
+type OnboardingQuestion = z.infer<typeof OnboardingQuestionSchema>;
+declare const OnboardingProfileSchema: z.ZodObject<{
+    experience: z.ZodOptional<z.ZodEnum<{
+        new: "new";
+        intermediate: "intermediate";
+        seasoned: "seasoned";
+    }>>;
+    tradingStyle: z.ZodOptional<z.ZodEnum<{
+        scalper: "scalper";
+        swing: "swing";
+        position: "position";
+        passive: "passive";
+    }>>;
+    riskAppetite: z.ZodOptional<z.ZodEnum<{
+        conservative: "conservative";
+        balanced: "balanced";
+        aggressive: "aggressive";
+    }>>;
+    favoriteSectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    avoidAssets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type OnboardingProfile = z.infer<typeof OnboardingProfileSchema>;
+declare const OnboardingStateResponseSchema: z.ZodObject<{
+    needsOnboarding: z.ZodBoolean;
+    onboardingState: z.ZodEnum<{
+        not_started: "not_started";
+        skipped: "skipped";
+        completed: "completed";
+    }>;
+    nextQuestion: z.ZodNullable<z.ZodObject<{
+        id: z.ZodEnum<{
+            experience: "experience";
+            trading_style: "trading_style";
+            risk_appetite: "risk_appetite";
+            note: "note";
+        }>;
+        prompt: z.ZodString;
+        options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        freeform: z.ZodBoolean;
+    }, z.core.$strip>>;
+    isLast: z.ZodBoolean;
+    answered: z.ZodNumber;
+    total: z.ZodNumber;
+    profile: z.ZodObject<{
+        experience: z.ZodOptional<z.ZodEnum<{
+            new: "new";
+            intermediate: "intermediate";
+            seasoned: "seasoned";
+        }>>;
+        tradingStyle: z.ZodOptional<z.ZodEnum<{
+            scalper: "scalper";
+            swing: "swing";
+            position: "position";
+            passive: "passive";
+        }>>;
+        riskAppetite: z.ZodOptional<z.ZodEnum<{
+            conservative: "conservative";
+            balanced: "balanced";
+            aggressive: "aggressive";
+        }>>;
+        favoriteSectors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        avoidAssets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type OnboardingStateResponse = z.infer<typeof OnboardingStateResponseSchema>;
+declare const OnboardingAnswerRequestSchema: z.ZodObject<{
+    questionId: z.ZodEnum<{
+        experience: "experience";
+        trading_style: "trading_style";
+        risk_appetite: "risk_appetite";
+        note: "note";
+    }>;
+    value: z.ZodString;
+}, z.core.$strip>;
+type OnboardingAnswerRequest = z.infer<typeof OnboardingAnswerRequestSchema>;
+
 declare const TradeLinkSchema: z.ZodObject<{
     link: z.ZodString;
     platform: z.ZodString;
@@ -375,6 +491,11 @@ declare class AgentChatClient {
         code?: string;
     }): Promise<SelfLinkResult>;
     unlinkWallet(): Promise<SelfUnlinkResult>;
+    getOnboardingState(surface: ChatSurface): Promise<OnboardingStateResponse>;
+    getOnboardingQuestions(surface: ChatSurface): Promise<OnboardingQuestion[]>;
+    submitOnboardingAnswer(surface: ChatSurface, body: OnboardingAnswerRequest): Promise<OnboardingStateResponse>;
+    skipOnboarding(surface: ChatSurface): Promise<OnboardingStateResponse>;
+    resetOnboarding(): Promise<OnboardingStateResponse>;
 }
 
-export { type TwitterSource as $, AgentChatClient as A, type SessionSummary as B, type CancelResult as C, SessionSummarySchema as D, ErrorEventSchema as E, type SetConfirmationsResult as F, SetConfirmationsResultSchema as G, type SetExecutionResult as H, SetExecutionResultSchema as I, SourcesEventSchema as J, StatusEventSchema as K, type LinkStatus as L, type StreamEvent as M, type SuggestedAction as N, SuggestedActionSchema as O, type PendingAction as P, type TicketAction as Q, TicketActionSchema as R, type SelfLinkResult as S, ThinkingEventSchema as T, type TicketStatus as U, TicketStatusSchema as V, TokenEventSchema as W, type TradeLink as X, TradeLinkSchema as Y, type TradeSettings as Z, TradeSettingsSchema as _, type AgentChatClientConfig as a, TwitterSourceSchema as a0, type AgentChatMessage as b, AgentChatMessageSchema as c, type AgentEvent as d, type AgentWireEvent as e, AgentWireEventSchema as f, CancelResultSchema as g, type ChatMode as h, ChatModeSchema as i, type ChatResult as j, ChatResultSchema as k, type ChatSurface as l, ChatSurfaceSchema as m, type CitationSource as n, CitationSourceSchema as o, type ConfirmResult as p, ConfirmResultSchema as q, LinkStatusSchema as r, PendingActionSchema as s, SelfLinkResultSchema as t, type SelfUnlinkResult as u, SelfUnlinkResultSchema as v, type Session as w, type SessionListItem as x, SessionListItemSchema as y, SessionSchema as z };
+export { StatusEventSchema as $, AgentChatClient as A, OnboardingQuestionSchema as B, type CancelResult as C, type OnboardingState as D, ErrorEventSchema as E, type OnboardingStateResponse as F, OnboardingStateResponseSchema as G, OnboardingStateSchema as H, PendingActionSchema as I, SelfLinkResultSchema as J, type SelfUnlinkResult as K, type LinkStatus as L, SelfUnlinkResultSchema as M, type Session as N, type OnboardingAnswerRequest as O, type PendingAction as P, type SessionListItem as Q, SessionListItemSchema as R, type SelfLinkResult as S, SessionSchema as T, type SessionSummary as U, SessionSummarySchema as V, type SetConfirmationsResult as W, SetConfirmationsResultSchema as X, type SetExecutionResult as Y, SetExecutionResultSchema as Z, SourcesEventSchema as _, type AgentChatClientConfig as a, type StreamEvent as a0, type SuggestedAction as a1, SuggestedActionSchema as a2, ThinkingEventSchema as a3, type TicketAction as a4, TicketActionSchema as a5, type TicketStatus as a6, TicketStatusSchema as a7, TokenEventSchema as a8, type TradeLink as a9, TradeLinkSchema as aa, type TradeSettings as ab, TradeSettingsSchema as ac, type TwitterSource as ad, TwitterSourceSchema as ae, type AgentChatMessage as b, AgentChatMessageSchema as c, type AgentEvent as d, type AgentWireEvent as e, AgentWireEventSchema as f, CancelResultSchema as g, type ChatMode as h, ChatModeSchema as i, type ChatResult as j, ChatResultSchema as k, type ChatSurface as l, ChatSurfaceSchema as m, type CitationSource as n, CitationSourceSchema as o, type ConfirmResult as p, ConfirmResultSchema as q, LinkStatusSchema as r, OnboardingAnswerRequestSchema as s, type OnboardingOption as t, OnboardingOptionSchema as u, type OnboardingProfile as v, OnboardingProfileSchema as w, type OnboardingQuestion as x, type OnboardingQuestionId as y, OnboardingQuestionIdSchema as z };

package/dist/index.cjs

@@ -248,6 +248,49 @@ var AgentChatMessageSchema = zod.z.looseObject({
   images: zod.z.array(zod.z.string()).nullish(),
   suggestedAction: SuggestedActionSchema.nullish()
 });
+var OnboardingQuestionIdSchema = zod.z.enum([
+  "experience",
+  "trading_style",
+  "risk_appetite",
+  "note"
+]);
+var OnboardingStateSchema = zod.z.enum([
+  "not_started",
+  "skipped",
+  "completed"
+]);
+var OnboardingOptionSchema = zod.z.object({
+  value: zod.z.string(),
+  label: zod.z.string(),
+  description: zod.z.string().optional()
+});
+var OnboardingQuestionSchema = zod.z.object({
+  id: OnboardingQuestionIdSchema,
+  prompt: zod.z.string(),
+  options: zod.z.array(OnboardingOptionSchema).optional(),
+  freeform: zod.z.boolean()
+});
+var OnboardingProfileSchema = zod.z.object({
+  experience: zod.z.enum(["new", "intermediate", "seasoned"]).optional(),
+  tradingStyle: zod.z.enum(["scalper", "swing", "position", "passive"]).optional(),
+  riskAppetite: zod.z.enum(["conservative", "balanced", "aggressive"]).optional(),
+  favoriteSectors: zod.z.array(zod.z.string()).optional(),
+  avoidAssets: zod.z.array(zod.z.string()).optional(),
+  note: zod.z.string().optional()
+});
+var OnboardingStateResponseSchema = zod.z.object({
+  needsOnboarding: zod.z.boolean(),
+  onboardingState: OnboardingStateSchema,
+  nextQuestion: OnboardingQuestionSchema.nullable(),
+  isLast: zod.z.boolean(),
+  answered: zod.z.number(),
+  total: zod.z.number(),
+  profile: OnboardingProfileSchema
+});
+var OnboardingAnswerRequestSchema = zod.z.object({
+  questionId: OnboardingQuestionIdSchema,
+  value: zod.z.string()
+});
 
 // src/stream.ts
 async function* parseSseStream(body) {
@@ -455,6 +498,48 @@ var AgentChatClient = class {
   unlinkWallet() {
     return this.http.json("DELETE", "/auth/link-wallet/self").then((raw) => SelfUnlinkResultSchema.parse(raw));
   }
+  // ── Onboarding (deterministic, FE-controlled) ──────────────────────
+  // Drive a wizard: read state, render `nextQuestion`, POST an answer (get the
+  // same shape back), or skip/reset. `surface` is the client surface — drives
+  // per-surface question phrasing server-side. The userId is the JWT caller,
+  // never sent in the body.
+  /** Current onboarding state for the caller on this surface (gate + next
+   *  question + progress + current `profile` picks). Returns the same shape
+   *  submitOnboardingAnswer/skip do. */
+  getOnboardingState(surface) {
+    return this.http.json(
+      "GET",
+      `/onboarding/state?surface=${encodeURIComponent(surface)}`
+    ).then((raw) => OnboardingStateResponseSchema.parse(raw));
+  }
+  /** Ordered onboarding questions for the surface (surface-static; no per-user
+   *  state). Closed questions carry `options`; the free-text note has none. */
+  getOnboardingQuestions(surface) {
+    return this.http.json(
+      "GET",
+      `/onboarding/questions?surface=${encodeURIComponent(surface)}`
+    ).then((raw) => raw.map((q) => OnboardingQuestionSchema.parse(q)));
+  }
+  /** Record one answer, then get the new state shape (next question or done). */
+  submitOnboardingAnswer(surface, body) {
+    return this.http.json(
+      "POST",
+      `/onboarding/answer?surface=${encodeURIComponent(surface)}`,
+      body
+    ).then((raw) => OnboardingStateResponseSchema.parse(raw));
+  }
+  /** Smart skip (parity with TG): skipping the optional last note step COMPLETES
+   *  onboarding with style+risk captured; skipping earlier bails the whole flow. */
+  skipOnboarding(surface) {
+    return this.http.json(
+      "POST",
+      `/onboarding/skip?surface=${encodeURIComponent(surface)}`
+    ).then((raw) => OnboardingStateResponseSchema.parse(raw));
+  }
+  /** Retake — clears persona + resets to not_started so the flow re-runs. */
+  resetOnboarding() {
+    return this.http.json("POST", "/onboarding/reset").then((raw) => OnboardingStateResponseSchema.parse(raw));
+  }
 };
 
 exports.AgentChatClient = AgentChatClient;
@@ -472,6 +557,13 @@ exports.ConflictError = ConflictError;
 exports.ErrorEventSchema = ErrorEventSchema;
 exports.ForbiddenError = ForbiddenError;
 exports.LinkStatusSchema = LinkStatusSchema;
+exports.OnboardingAnswerRequestSchema = OnboardingAnswerRequestSchema;
+exports.OnboardingOptionSchema = OnboardingOptionSchema;
+exports.OnboardingProfileSchema = OnboardingProfileSchema;
+exports.OnboardingQuestionIdSchema = OnboardingQuestionIdSchema;
+exports.OnboardingQuestionSchema = OnboardingQuestionSchema;
+exports.OnboardingStateResponseSchema = OnboardingStateResponseSchema;
+exports.OnboardingStateSchema = OnboardingStateSchema;
 exports.PendingActionSchema = PendingActionSchema;
 exports.RateLimitError = RateLimitError;
 exports.SelfLinkResultSchema = SelfLinkResultSchema;