Skip to content

Commit d6ced85

Browse files
author
ci-bot
committed
api implementation
1 parent bcb3ebf commit d6ced85

File tree

9 files changed

+594
-118
lines changed

9 files changed

+594
-118
lines changed

‎WALKTHROUGH_API.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Walkthrough API – Brief
2+
3+
## Overview
4+
5+
The walkthrough system provides guided tours within Remix IDE. Walkthroughs are managed by admins, targeted to users via **audience rules** (same system as notifications & feedback), and tracked per-user with completion status so the frontend can distinguish seen vs unseen.
6+
7+
All walkthrough endpoints live on the **notification** service (port 3013).
8+
9+
---
10+
11+
## Database Tables
12+
13+
| Table | Purpose |
14+
|-------|---------|
15+
| `walkthroughs` | Walkthrough definitions (slug, name, description, source_plugin, active/dates/priority, soft delete) |
16+
| `walkthrough_steps` | Ordered steps with target_selector, title, content, placement, click interaction, pre_action JSON |
17+
| `walkthrough_audience` | Audience rules (same 9 types as notifications/feedback) |
18+
| `walkthrough_completions` | Tracks which users have seen each walkthrough (UNIQUE walkthrough_id + user_id) |
19+
20+
### Audience Rule Types
21+
22+
`all_users`, `account_group`, `feature_group`, `product`, `subscription_plan`, `credit_min`, `credit_max`, `tag`, `provider`
23+
24+
Multiple rules use OR logic — user matches if **any** rule matches.
25+
26+
---
27+
28+
## WalkthroughDefinition
29+
30+
The user endpoint returns a **JSON array** of walkthrough objects with embedded steps.
31+
32+
| Field | Type | Required | Description |
33+
|----------------|---------------------|----------|----------------------------------------------|
34+
| `id` | `number` | yes | Auto-increment ID |
35+
| `slug` | `string` | yes | Unique slug identifier |
36+
| `name` | `string` | yes | Display name shown in the UI |
37+
| `description` | `string` | no | Short description of the walkthrough |
38+
| `source_plugin`| `string` | no | Plugin that registered it (defaults to `"api"`) |
39+
| `priority` | `number` | yes | Sort priority (higher = more important) |
40+
| `completed` | `boolean` | yes | Whether the current user has completed it |
41+
| `completed_at` | `string \| null` | yes | ISO timestamp or null |
42+
| `steps` | `WalkthroughStep[]` | yes | Ordered list of steps |
43+
44+
## WalkthroughStep
45+
46+
| Field | Type | Required | Description |
47+
|------------------|--------------------------------------------|----------|----------------------------------------------------------|
48+
| `sort_order` | `number` | yes | Step order index (0-based) |
49+
| `target_selector`| `string` | yes | CSS selector for the element to highlight |
50+
| `title` | `string` | yes | Popover title |
51+
| `content` | `string` | yes | Body content (supports HTML) |
52+
| `placement` | `"top" \| "bottom" \| "left" \| "right"` | no | Popover placement relative to the target |
53+
| `click_selector` | `string` | no | CSS selector of an element to click before showing step |
54+
| `click_delay` | `number` | no | Delay in ms after click before showing step (default 500)|
55+
| `pre_action` | `PreAction` | no | Plugin call to execute before showing this step |
56+
57+
## PreAction
58+
59+
| Field | Type | Required | Description |
60+
|----------|----------|----------|----------------------------------|
61+
| `plugin` | `string` | yes | Plugin name to call |
62+
| `method` | `string` | yes | Method to invoke on the plugin |
63+
| `args` | `any[]` | no | Arguments passed to the method |
64+
65+
---
66+
67+
## User Endpoints
68+
69+
Base path: `/walkthroughs` (requires auth)
70+
71+
### Get My Walkthroughs
72+
```
73+
GET /walkthroughs
74+
```
75+
Returns all walkthroughs that are active, within date window, and match the user's audience.
76+
77+
### Mark Walkthrough as Completed
78+
```
79+
POST /walkthroughs/:id/complete
80+
```
81+
Idempotent — calling multiple times is safe.
82+
83+
---
84+
85+
## Admin Endpoints
86+
87+
Base path: `/walkthroughs/admin` (requires auth + admin)
88+
89+
- `GET /walkthroughs/admin` — List all walkthroughs
90+
- `GET /walkthroughs/admin/:id` — Get walkthrough with steps + audience
91+
- `POST /walkthroughs/admin` — Create walkthrough
92+
- `PATCH /walkthroughs/admin/:id` — Update walkthrough
93+
- `DELETE /walkthroughs/admin/:id` — Soft delete
94+
- `PUT /walkthroughs/admin/:id/steps` — Replace steps
95+
- `GET /walkthroughs/admin/:id/steps` — Get steps
96+
- `PUT /walkthroughs/admin/:id/audience` — Replace audience rules
97+
- `GET /walkthroughs/admin/:id/audience` — Get audience rules
98+
- `DELETE /walkthroughs/admin/:id/completions/:userId` — Reset user completion
99+
100+
---
101+
102+
## Frontend Integration (implemented)
103+
104+
### Files Changed
105+
106+
| File | Purpose |
107+
|------|---------|
108+
| `libs/endpoints-helper/src/index.ts` | Added `walkthroughs` endpoint URL |
109+
| `libs/remix-api/src/lib/plugins/walkthrough-api.ts` | Added `ApiWalkthrough`, `ApiWalkthroughStep`, `ApiWalkthroughsResponse` types, `completed`/`apiId`/`priority` fields on `WalkthroughDefinition`, and `markCompleted` method |
110+
| `apps/remix-ide/src/walkthroughService.tsx` | API client integration, auth listener, fetch-on-login, snake_case→camelCase mapping, completion tracking |
111+
| `libs/remix-ui/walkthrough/src/lib/remix-ui-walkthrough.tsx` | Seen/unseen badges, sorted list (new first), replay button for completed |
112+
113+
### Data Flow
114+
115+
```
116+
App startup / user login
117+
│
118+
├─ authStateChanged → set token on ApiClient
119+
│
120+
├─ GET /walkthroughs → fetch audience-matched walkthroughs
121+
│
122+
├─ Map snake_case → camelCase WalkthroughDefinition
123+
│
124+
├─ Merge with built-in walkthroughs, render list
125+
│ (unseen first, sorted by priority, completed shown with ✓)
126+
│
127+
├─ User clicks "Start Tour" → execute steps via driver.js
128+
│
129+
└─ Last step finished → POST /walkthroughs/:apiId/complete
130+
│
131+
└─ Update local state (mark as completed, re-render)
132+
```
133+
134+
### Example payload
135+
136+
```json
137+
{
138+
"walkthroughs": [
139+
{
140+
"id": 1,
141+
"slug": "remix-intro",
142+
"name": "Getting Started with Remix",
143+
"description": "A quick tour of the Remix IDE interface.",
144+
"source_plugin": "walkthrough",
145+
"priority": 10,
146+
"completed": false,
147+
"completed_at": null,
148+
"steps": [
149+
{
150+
"sort_order": 0,
151+
"target_selector": "[data-id=\"verticalIconsHomeIcon\"]",
152+
"title": "Welcome",
153+
"content": "This is your home button.",
154+
"placement": "right",
155+
"click_selector": null,
156+
"click_delay": null,
157+
"pre_action": null
158+
}
159+
]
160+
}
161+
],
162+
"count": 1
163+
}
164+
```

‎apps/remix-ide/src/walkthrough-definitions.ts‎

Lines changed: 73 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import { WalkthroughDefinition } from '@remix-api'
88

99
export const builtinWalkthroughs: WalkthroughDefinition[] = [
1010
{
11-
id: 'remix-intro',
11+
id: 'remix-intro-basics',
1212
name: 'Getting Started with Remix',
1313
description: 'A quick tour of the Remix IDE interface and basic features.',
1414
sourcePlugin: 'walkthrough',
@@ -53,11 +53,33 @@ export const builtinWalkthroughs: WalkthroughDefinition[] = [
5353
},
5454
},
5555
{
56-
targetSelector: '[data-id="terminalContainer"]',
57-
title: 'Terminal',
58-
content: 'The terminal shows transaction logs, compilation output, and lets you run JavaScript/Solidity scripts.',
59-
placement: 'top',
56+
targetSelector: '[plugin="remixaiassistant"]',
57+
title: 'AI Assistant',
58+
content: 'Remix has a built-in <b>AI assistant</b> that can explain code, find bugs, suggest fixes, and even generate contracts from a prompt. Open it anytime to chat with AI about your Solidity code.',
59+
placement: 'right',
60+
preAction: {
61+
plugin: 'menuicons',
62+
method: 'select',
63+
args: ['remixaiassistant'],
64+
},
65+
},
66+
{
67+
targetSelector: '[plugin="dgit"]',
68+
title: 'Git Integration',
69+
content: 'The <b>Git plugin</b> lets you initialize repos, commit changes, push/pull to GitHub, and manage branches — all without leaving the IDE.',
70+
placement: 'right',
71+
preAction: {
72+
plugin: 'menuicons',
73+
method: 'select',
74+
args: ['dgit'],
75+
},
6076
},
77+
{
78+
targetSelector: '[data-id="github-dropdown-toggle-login"]',
79+
title: 'GitHub Login',
80+
content: 'Click here to <b>sign in with GitHub</b>. Once connected you can clone private repos, push changes, and publish Gists directly from Remix.',
81+
placement: 'bottom',
82+
}
6183
],
6284
},
6385
{
@@ -68,61 +90,52 @@ export const builtinWalkthroughs: WalkthroughDefinition[] = [
6890
steps: [
6991
{
7092
targetSelector: '[plugin="filePanel"]',
71-
title: 'Step 1: Open a Contract',
72-
content: 'First, open a Solidity file from the File Explorer. You can use one of the default workspace templates.',
93+
title: 'Step 1: Create a Workspace',
94+
content: 'We\'ll create a fresh workspace with a sample contract for you. A new <b>"LearnDeploy"</b> workspace is being set up with the default Remix template.',
7395
placement: 'right',
96+
preAction: [
97+
{ plugin: 'filePanel', method: 'createWorkspace', args: ['LearnDeploy', 'remixDefault', false] },
98+
{ plugin: 'menuicons', method: 'select', args: ['filePanel'] },
99+
],
100+
},
101+
{
102+
targetSelector: '#editor-container',
103+
title: 'Step 2: Open the Contract',
104+
content: 'Here is <b>1_Storage.sol</b> — a simple contract that stores and retrieves a number. Take a look at the code!',
105+
placement: 'left',
74106
preAction: {
75-
plugin: 'menuicons',
76-
method: 'select',
77-
args: ['filePanel'],
107+
plugin: 'fileManager',
108+
method: 'open',
109+
args: ['contracts/1_Storage.sol'],
78110
},
79111
},
80112
{
81113
targetSelector: '[plugin="solidity"]',
82-
title: 'Step 2: Open the Compiler',
83-
content: 'Click the Solidity Compiler icon to open the compilation panel.',
114+
title: 'Step 3: Open the Compiler',
115+
content: 'Click the <b>Solidity Compiler</b> icon in the side panel to open the compilation view.',
84116
placement: 'right',
85-
},
86-
{
87-
targetSelector: '#compileBtn',
88-
title: 'Step 3: Compile',
89-
content: 'Click "Compile" to compile your contract. Make sure the correct compiler version is selected.',
90-
placement: 'bottom',
91117
preAction: {
92118
plugin: 'menuicons',
93119
method: 'select',
94120
args: ['solidity'],
95121
},
96122
},
97123
{
98-
targetSelector: '[plugin="udapp"]',
99-
title: 'Step 4: Open Deploy Panel',
100-
content: 'Now switch to the Deploy & Run panel to deploy your compiled contract.',
101-
placement: 'right',
102-
},
103-
{
104-
targetSelector: '#Deploy',
105-
title: 'Step 5: Deploy',
106-
content: 'Select your contract and click "Deploy". By default, it deploys to the Remix VM — a simulated blockchain in your browser.',
124+
targetSelector: '#compileBtn',
125+
title: 'Step 4: Compile the Contract',
126+
content: 'We\'re compiling <b>1_Storage.sol</b> for you now. Watch the compiler panel — when it succeeds you\'ll see a green check mark.',
107127
placement: 'bottom',
108128
preAction: {
109-
plugin: 'menuicons',
110-
method: 'select',
111-
args: ['udapp'],
129+
plugin: 'solidity',
130+
method: 'compile',
131+
args: ['contracts/1_Storage.sol'],
112132
},
133+
clickDelay: 1000,
113134
},
114-
],
115-
},
116-
{
117-
id: 'remix-recorder',
118-
name: 'Transaction Recorder',
119-
description: 'Learn how to record and replay transactions across different environments.',
120-
sourcePlugin: 'walkthrough',
121-
steps: [
122135
{
123-
targetSelector: '#udappRecorderCard',
124-
title: 'Transactions Recorder',
125-
content: 'Save transactions (deployed contracts and function executions) and replay them in another environment. Transactions created in Remix VM can be replayed with an Injected Provider.',
136+
targetSelector: '[plugin="udapp"]',
137+
title: 'Step 5: Open the Deploy Panel',
138+
content: 'Now switch to <b>Deploy & Run Transactions</b>. This is where you deploy compiled contracts and interact with them.',
126139
placement: 'right',
127140
preAction: {
128141
plugin: 'menuicons',
@@ -131,23 +144,29 @@ export const builtinWalkthroughs: WalkthroughDefinition[] = [
131144
},
132145
},
133146
{
134-
targetSelector: '#udappRecorderUseLatest',
135-
title: 'Use Latest Compilation',
136-
content: 'If selected, the recorder will run transactions using the latest compilation result.',
137-
placement: 'right',
147+
targetSelector: '[data-id="Deploy - transact (not payable)"]',
148+
title: 'Step 6: Deploy!',
149+
content: 'We\'re deploying the Storage contract to the <b>Remix VM</b> for you — a simulated blockchain running in your browser. No real funds needed!',
150+
placement: 'bottom',
151+
clickSelector: '[data-id="deployAndRunClearInstances"]',
152+
clickDelay: 500,
138153
},
139154
{
140-
targetSelector: '#udappRecorderSave',
141-
title: 'Save Scenario',
142-
content: 'Once one or more transactions have been executed, click this button to save them as a scenario file.',
143-
placement: 'right',
155+
targetSelector: '*[data-shared="universalDappUiInstance"]',
156+
title: 'Step 7: Interact with Your Contract',
157+
content: 'Your contract is now deployed! The instance appears here. You can call <b>store()</b> to save a number and <b>retrieve()</b> to read it back. Try it out!',
158+
placement: 'top',
159+
clickSelector: '[data-id="Deploy - transact (not payable)"]',
160+
clickDelay: 2000,
144161
},
145162
{
146-
targetSelector: '#udappRecorderRun',
147-
title: 'Run Scenario',
148-
content: 'Open a scenario file and click this button to run it against the currently selected provider.',
149-
placement: 'right',
163+
targetSelector: '*[data-id="universalDappUiContractActionWrapper"]',
164+
title: 'Step 8: Contract Functions',
165+
content: 'Here are all the functions of your contract. <b>Orange</b> buttons are write functions (transactions) and <b>blue</b> buttons are read-only (free calls). Try calling <b>store()</b> with a number and then <b>retrieve()</b> to read it back! 🎉',
166+
placement: 'top',
167+
clickSelector: '[data-id="universalDappUiTitleExpander0"]',
168+
clickDelay: 500,
150169
},
151170
],
152171
},
153-
]
172+
]

0 commit comments

Comments
 (0)