Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

27.7 KB
Raw Blame

Login

Flow

  1. Navigate to /app. Unauthenticated sessions land on /app/welcome.
  2. Click the button named Continue with email in the a11y tree. (One click sometimes only focuses it — if no form appears in the next snapshot, click again.)
  3. fill the textbox labeled [email protected] with the email, click Continue.
  4. On the local stack the auth service is built with return_passwordless_code: the login response carries the one-time code and the frontend auto-verifies it, so you are logged in immediately — no code entry step ever appears. A code email is still sent and visible in Mailpit. Against a real deployment, expect a code-entry step instead: fetch the code from the user's inbox (locally: Mailpit). The sixth digit submits the code. A rejected code clears the boxes and refocuses them for retyping. The auth service allows five code checks a minute per address; past that the step shows "Too many attempts. Wait a minute, then try again." and keeps the code. Requesting a new code does not lift that wait.
  5. First login auto-creates the user, seeds onboarding content (a "Macro Support x " channel, a "Macro how to guide" doc favorite, three sample tasks), and lands on /app/home. The starter documents share a personal docs tag; the guide's # example is an inline mention of that same tag. A tag attachment failure does not block the remaining content; signup retries repair tags without resetting task priorities. The guide waits until its tag IDs resolve.

Agent accounts

/app/signup/agent is the agent signup page: Google or an emailed code, without the opening slides. The first slide of /app/signup links to it (Sign up as agent), as does /mobile-signup, and the marketing site's HTML carries a hidden notice pointing agents there. A new account made there, or by redeeming an invite sent with Invite as agent in Settings → Team → Members or team.invite(email, { agent: true }), is an agent. An existing account keeps its type. An agent invite email links to /app/signup/agent?team_invite=<id>; a signed-in account that isn't a new agent continues to /app/team-invite?id=<id>.

After the code or Google sign-in, an agent skips onboarding and goes to /app/agent-setup, a markdown page with the SDK token as plain page text, the product and SDK docs links, how to set a name and profile picture, install and pair macrod, and create more tokens, and a link to the app. The app shell sends an unconfirmed agent back here. An invited agent also joins the inviting team at this point; if that fails, the page says so and the invite stays pending: reloading tries again, and the emailed invite link still works after confirming. Each reload before following the link to /app/agent-setup/done replaces the token; afterwards the page redirects to the app.

An email agent signup skips the seeded content and marketing emails. A Google agent signup is flagged when the sign-in returns, after FusionAuth's user.create webhook has run, so it gets them like a person's signup. Requesting a code outside the agent signup page, or signing in with SSO outside it, reverts the account to a person unless it holds a token, has confirmed setup, or has a pending agent invite.

Production Google/SSO and inbox/calendar connections may return to either https://macro.com or https://www.macro.com. Verify connections from both hosts; the web inbox link flow returns to /app/inbox-link-callback on the originating host.

On desktop, connecting a Gmail or Outlook account, reconnecting one, or enabling calendar opens the selected provider's consent in the system browser. The app stays open; the callback is macro:///inbox-link-callback?link_id=..., which provisions the inbox using the existing app session and restores the saved layout, including its query and hash. Verify each enabled provider, including reconnects with email-only and calendar permissions. Check that opening consent alone does not report an account connected, that returning from consent shows the second account, and that canceling leaves the app usable and says nothing was connected. iOS and Android continue to use their native authentication sessions.

Every callback outcome is announced on web, desktop, and native. Init also succeeds when the provider's account chooser returns an account that is already connected (for example a Google Workspace user who signs in under a secondary domain): Connect another account then reports <address> is already connected with a hint to pick a different account, instead of Account connected. Only a plain add (mailbox consent, no reconnect target or login hint) checks this; reconnects and calendar upgrades of an existing inbox still report Account connected. To check, connect an account that is already in the inbox list and confirm the alert names it and no new row appears.

A consent that ends without a usable grant returns to the callback with email_link_error instead of a provisionable link_id: cancelled returns quietly, admin_consent_required shows the Microsoft approval dialog, gmail_not_granted (the email permissions were left unchecked on Google's screen, so nothing was connected and the auth service tried, best effort, to revoke the partial grant at Google unless an inbox for that address still works on it) shows a persistent Email access required prompt whose Try again reopens Connect email, and anything else shows a failure toast.

Temporary open signup in Develop

Once the temporary authentication-service override is deployed, Develop accepts new accounts with any email address regardless of signup allowlist membership or the configured bypass flag. Verify with an authorized test account outside macro.com that is absent from the allowlist. Email verification and provider sign-in still apply. See the authentication-service configuration guide for restoring allowlist enforcement.

GraphQL cache session lifecycle

For local browser checks signed in through the passwordless HTTP API, copy the returned cookies into the browser context and set localStorage macro:login to true before the app loads. The app uses that hint to start its identity check; the HttpOnly session cookie alone does not start it. Normal UI login sets the hint automatically. The backend still verifies the session.

Signed-out pages use the network client without creating the GraphQL cache, draft queue runner, or live-update subscriptions. Signing in activates them in the same tab, including after a session expiry. Queued draft writes wait for authenticated user info; unrelated mutations can continue draining.

A confirmed expiry loads /welcome as a new page, as logout does, so email drafts work after the next sign-in. Verify expiry followed by signing into a different account: the new account's lists must load and receive live updates, email composers must accept input, and the previous account's cached data must be absent. Logout wipes local caches before retiring their clients. Mounted query observers must receive the next account's data after the wipe. Previous account data must not return through initial data, placeholder data, or a later query reset.

CI deploy-preview authentication

PR previews at https://<id>.preview.macro.com/app use the dev backend and its shared .macro.com HttpOnly cookies (dev-macro-access-token and dev-macro-refresh-token). The login hint is host-only and macro:login localStorage is origin-scoped, so a fresh preview has neither. Preview startup must check identity anyway; the hostname is not proof of authentication. Account queries and WebSockets still wait for a confirmed authenticated user.

Verify in a browser signed into https://dev.macro.com: open a fresh preview hostname (or clear only that preview's localStorage and login hint, keeping the shared dev cookies). It should request https://dev-gateway.macro.com/auth/user/legacy_user_permissions and enter the signed-in app without another login. Repeat in a clean browser context: the identity check should fail without starting account services, and a public document should remain readable. Ordinary signed-out public links without a login hint should not start identity checks or account services.

Hosted-dev proxy SSO

On an allowed OAuth origin such as https://localhost:<port>, Google/SSO sign-in navigates the browser to /__macro_dev/gateway/auth/login/sso with is_mobile=true to request the session-code handoff. The original_url remains the browser destination (including its query and hash). Returning from the provider redeems the session code to establish cookies locally. This browser flow must not open a native authentication session. Verify the redirect separately from provider completion; arbitrary development hostnames are not on the hosted OAuth redirect allowlist.

Native iOS 27

The native welcome screen offers Create new account and Log into existing account before the login form. Startup and background/foreground resume work with the scene lifecycle enabled; Macro remains single-window on iPhone and iPad. The iPad welcome screen can show an Optimized for iPhone notice. Mobile resume is delivered per window, independently of ordinary focus changes. A custom-scheme link to macro://app/login now opens the login form both while Macro is running and when it cold-starts the app. Verify both cases separately. When signed out, an ordinary launch with no URL should show the welcome screen. When signed in, the session should survive restart and the app should open its authenticated landing view without replaying an old deep link. For simulator checks, xcrun devicectl device process launch --device <udid> --payload-url 'macro://app/login' com.macro.app.prod delivers the link without simctl openurl's confirmation dialog. Terminate Macro first for the cold case. Signed universal links and share-sheet flows still need end-to-end verification; see the Tauri guide and repeatable iOS smoke test.

Signed-out GraphQL regression

Open a public sharing link with stale login hints and an expired session. Once user-info returns 401, GraphQL must use the plain network client, dispose any normalized cache and live-update session, and clear the login hints. Repeat with retained user-info data from an earlier successful request. A network failure or 5xx must not end the session; successful sign-in must re-enable eligible caching.

Native sign-out

In the desktop, iOS, and Android apps, Sign out reloads the webview onto the sign-in screen. The reloaded document must start on #/login, never on the route it signed out from: that route has no session left to load and shows loading placeholders indefinitely. Sign out from Settings → Account and from Home, and check that native_webview_started reports a #/login URL.

Native Android

If a signed-out page shows the bottom Login / Sign Up banner, both buttons must sit above Android's navigation bar. Verify that Login is tappable with three-button navigation as well as gesture navigation.

The Android welcome screen also offers Create new account and Log into existing account. Google sign-in opens a system browser Auth Tab; completing or canceling returns to Macro. Cancel and retry should open a fresh attempt. Enter provider passwords and verification codes only in that browser, never in agent messages. For browsers using the Custom Tabs fallback, verify that the callback returns to the original Macro task. A callback for another attempt must leave the current attempt pending; a callback after process death must not restore that attempt. The first Google sign-in after a fresh install must land in the app, even while an over-the-air update finishes downloading: an update reload during the sheet or the session-code redemption used to return the user to Login, with the second tap then signing straight in. Check that PostHog shows no native_webview_started reload onto #/login right after the login event.

After signing in, test background/foreground, force-stop/relaunch, logout, and signing in as another account. An entity link opened while signed out should remain pending until authentication completes. The destination expires after 30 minutes and explicit logout clears it. Test both cold and warm delivery; forcing an Android intent to Macro proves routing, not verified App Links. Root links must preserve query parameters through the welcome or inbox redirect, including when Android delivers the link after the session gate mounts. Test with a harmless marker query; checkout return parameters can trigger analytics and license refreshes and should only be exercised in a checkout test. See Android development for build commands and certificate-dependent domain verification. Provider completion, account linking, and verified links still require end-to-end qualification.

GitHub reconnect prompt

On native mobile, the Reconnect GitHub prompt hides while the authentication browser is open. Canceling or failing authentication restores the prompt so the user can retry; successful reconnection keeps it hidden. Verify cancel followed by retry, browser failure, and failure to start OAuth. Repeated taps while a flow is pending must start only one attempt. On the web, a successful OAuth kickoff navigates away and the prompt stays hidden during that navigation. Use browser Back to return from GitHub: when the page is restored from BFCache, it refreshes link status and restores the retry prompt only if reconnection is still needed.

Desktop onboarding

New desktop users enter the same flow from /app/signup, /app/login, or /app/onboarding. Marketing Get Started links open /app/signup. Existing members and native mobile keep their existing routes.

Signed-out /app/signup starts at the workspace color picker, followed by feature interests and security. No account is required for these slides. The signed-out page should remain stable after the session check returns 401; it must not alternate with the loading screen or reset a selected color. Verify that Continue advances without signing in. Below the color picker, "Already have an account? Sign in instead" opens /app/login. At the work-email step, Connect work email uses Google sign-up to create the Macro account and link the primary inbox. This step offers Google sign-up only, with no alternate email button. The chosen accent and work step survive the OAuth redirect; after authentication the accent is saved to the user's theme and setup resumes at work email. Regular /app/login retains the direct sign-in screen.

Onboarding follows the app's light/dark setting. Light mode uses the marketing cream background, black headings, muted warm text, and brighter ivory inputs and integration tiles. Dark mode retains its black palette. Verify both modes at desktop and mobile widths, including the below-fold security and pricing details. For a safe local walkthrough with simulated connections and billing, use the real view fixture documented in apps/web/src/features/onboarding/browser-test/README.md; /?view=flow&theme=cream forces its cream preview without changing account settings.

The steps are workspace color, feature interests, security, work Google account, personal Google account, tools, team, and plan selection. Color selection forks the default Macro Light or Macro Dark theme for the current mode and pins the custom accent palette; it does not modify a built-in theme. Cream mode hides Pearl and centers the remaining five swatches. A selected Pearl falls back to Mint when entering cream mode; Pearl stays available in dark mode. Cream slab headings use weight 330 (15 above dark mode) with the same sizing and line breaks. Interests are visual preferences only. Security and Google steps have a Read more section below the fold.

Work and personal account buttons use the existing Gmail linking flow. Skipping work email skips the secondary-account prompt. Verify that a Google return restores the correct step, shows the connected address, and allows continuation.

Tools show a stable featured list: Linear, Notion, Slack, then startup tools such as PostHog and Stripe, followed by small-business tools such as QuickBooks. The featured Pipedream metadata is checked in; the remaining catalog uses one live paginated query. Search still covers the full directory. Verify load more, search, cancel/retry connection, and state persistence on return. Paging and Slack aliases must not duplicate cards. New Slack connections use slack_v2; existing slack accounts remain recognized. Production release requires a real Slack authorization and a successful read-only tool call, not just fixture tests. Cards use the Pipedream logo, with bundled icons and a generic plug as fallbacks. The catalog scrolls with the page; Continue stays visible in a sticky footer. At desktop and phone widths, verify scrolling over the cards moves the page, the last row remains reachable, and Continue stays fully visible after searching.

GitHub uses Macro's native OAuth/re-authorization flow and returns to the tools step. It shows Account linked, distinct from agent-tool readiness. A Configure GitHub repositories action opens native GitHub App installation; repository access must not be inferred from the account link. No Pipedream GitHub card is offered. The same setup remains available in Settings.

Gmail and Google Calendar are hidden, including search and later pages. Google Drive and Google Sheets remain available in browse and search, with separate Pipedream connection state. Native Gmail and Calendar consent does not request Drive or Sheets scopes. Enabled native MCP and Pipedream connections show Connected. Disabled existing connections show Enable and reuse their stored authorization. Native and hosted tools coexist in both chat and sandbox agents, with native preference for known overlapping providers and Slack alias deduplication. Connection status failures have an explicit retry; they must not prevent independent providers such as native GitHub from connecting. Verify unknown status never launches a duplicate OAuth flow and continuation remains possible. Someone already on a team when they leave the tools step (joined by invite link or by domain) never sees the team step: Continue goes to the plan step, or finishes for a licensed member, and Back from plan returns to tools. Pending email invites still show on the team step for acceptance, and a team created there shows the You're on confirmation. Team setup retains invite acceptance, domain suggestions, and editable invite recipients; submitting the form sends real invitations. On the create-team form, type a workspace name and edit a teammate address, then allow onboarding/contacts queries to refresh. The same inputs must retain their values and focus as suggestions arrive or a background request fails. Pending queries must show local loading states without suspending the flow. When the server suggests a work domain, the create form has no Skip button and shows two switches, both on by default and marked recommended: Allow @domain emails to join and Notify your team via email. Creating the team with the first on sets the team's auto-join domain. With both on, it then, after the invites, emails up to 25 of the creator's same-domain contacts who are not on Macro, invited, or already sent a notice (POST /team/domain-notice). The notice switch is disabled and reads off while domain join is off, because the server sends nothing to a team without an auto-join domain; turning domain join back on restores its earlier setting. Each switch has an info button beside it that explains the setting in a tooltip on hover or focus, and in a popover on tap on touch devices; pressing it never toggles the switch. Creating the team does not leave the step: it switches to the You're on confirmation, the same panel members who were already on a team (auto-joined or invite-accepted) see. That panel has Copy invite link beside Continue; it copies the team's /app/team-invite?link= URL, creating the link when the team has none. Members who may invite (admins and owners, or anyone when non-admin invites are on) can create the first link; when they can't, the button shows an error toast.

Personal-domain accounts (no suggested work domain) never see the create-team form. The step shows an Invite friends. referral screen instead ("Get $10 of AI credit for each person who signs up."), with friend email rows, Copy referral link (/app/signup?referral_code=), Send N invites (one referral invite per address, then the plan step; no team is created), and Skip for now. Send stays disabled until an address is valid; if none of the invites can be sent, the addresses stay on screen. On phones, the paired buttons stack full width.

Members with an active or trialing license, including a license from their team, finish directly from the team step without visiting the plan page. The Continue button reads "Opening your workspace…" while saving; a failed save leaves the team step available to retry. Checkout returns still use the plan step to confirm payment. Session refreshes must preserve the mounted onboarding flow so completion finishes instead of repeatedly flashing or restarting.

Finishing setup saves the onboarding record before marking the tutorial complete. The confirmed tutorial save updates the session cache before leaving. A successful finish must not show "Couldn't finish setup — please try again", including when a background session refresh overlaps it.

The final screen shows “Free Claude & GPT for 30 days” and the trial button only after the server confirms first-subscription eligibility. Returning customers without an existing subscription see “Get more with Pro.” and Get Pro with paid monthly terms. Existing subscribers see Manage subscription to review their subscription and payment details. The “See more” scroll cue opens the pricing grid below, comparing Free, Pro, and Max. The grid loads monthly subscription prices from the billing catalog and describes Max as 10× Pro usage, without displaying dollar-denominated included AI allowances. Monthly prices use the compact /usr/mo unit on one line; Free email branding reads “Sent with Macro”. Free completes onboarding without a card. Pro returns to the account-specific Pro offer; Max starts standard paid checkout with no trial period. The trial copy and button stay on the Pro offer. The trial button requests 30 days free through Stripe Checkout, with no coupon required. Stripe collects the payment method for billing after the trial. Only a customer's first subscription qualifies, including canceled subscriptions in that check. Eligibility loading or failure disables Pro checkout without advertising a trial; a failed lookup offers Try again. A trial rejected at checkout shows the server explanation and refreshes eligibility, without automatically retrying as a paid purchase. Invite promotions retain their own offer and terms. Cancellation returns to this step. A successful return polls the server's license state, completes onboarding, and enters the app without an extra confirmation click. A pending webhook shows a retryable confirmation state. If the catalog cannot load, Free remains available, Pro still returns to its offer, and Max checkout stays disabled until prices can be loaded with the retry action. Both completion paths preserve an original next destination and otherwise land on Home (/app/home). Old saved email, connector, building, and summary step names are migrated on resume. A lifecycle email can open a specific step with /app/onboarding?step=<step> (see onboarding). The step is kept in localStorage for that user. A checkout return or an in-progress Google sign-up still wins, then saved progress, then the link.

Public onboarding preview

The standalone marketing development route /onboarding-preview.html continues from team setup to a final trial screen. The payment card starts with Apple Pay, Google Pay, and the card-number input, with no plan header or divider. The card scrolls internally at a maximum of 360px or half the viewport height. Entering at least 15 digits in the local preview input reveals expiration, security code, country, and ZIP previews; clearing it hides them again. Use a test number such as 4242 4242 4242 4242. For eligible customers, the primary CTA reads Start 30 day trial, with the billing and cancellation note immediately below it. The quiet Continue as Guest scroll cue beneath it moves focus to the below-fold Guest and Pro comparison, using the same layout as the security details. The table includes email account limits, the email watermark, AI, storage, and calls. Each comparison column ends with its own compact CTA. Continue as Guest finishes the preview without a confirmation modal; Continue with Pro in the comparison returns to the payment section and its heading. Reduced-motion users scroll immediately. Wallet buttons only display a preview message. The card number stays in the input only and is never sent or saved; the remaining fields are display-only. Both plan continuation buttons finish the preview at the login URL; they do not purchase a subscription. Back returns to team setup. This payment mock remains preview-only; the authenticated flow instead opens Stripe Checkout as described above.

Mailpit (local email)

  • UI: http://localhost:<mailpit-port>/
  • API: curl -s http://localhost:<mailpit-port>/api/v1/messages — newest message first. Login codes arrive as subject Your Macro login code with snippet Your Macro login code: NNNNNN.

Known crash on first landing (local)

Immediately after login the app navigates to /app/home and can throw a full-screen error dialog: "Something went terribly wrong — Cannot read properties of undefined (reading 'id')". Console shows Failed to init email link on login with a 404 on GET /auth/link/github/status and a 400 on POST /email/email/init. This is cosmetic-ish and fully recoverable: click the dialog's Home button, then wait for the sidebar text Go to Email to appear.

Session persistence

The session lives in cookies (local-macro-access-token, local-macro-refresh-token). It survives page reloads but not a browser-profile restart — if the shared Chromium is restarted with a fresh profile you must log in again. Workspace data (docs, channels, tasks) persists on the backend across logins for the same email.

Stalled session refresh

When an expired session triggers cookie-auth refresh, every waiting request and socket setup shares one refresh, which settles within 12 seconds as a retryable network failure, or sooner when the native network path drops. Cancelling one view stops only its own wait. After a timeout the next request starts a fresh refresh; a timeout never signs the user out or reloads the app. Returning to the app expires a refresh that started more than 12 seconds earlier, so requests after a resume start a fresh one instead of waiting.

Google OAuth through a remote local stack

Use the stack's configured HTTPS frontend origin for Google account linking. In local mode, authentication accepts that exact origin (including port) as a return URL. Remote hostnames must use HTTPS; hosted environments retain their existing redirect allowlist.

If Google redirects to http://localhost:<auth-port>/oauth2/google/callback, forward that port from the browser's machine to the VM's authentication port in addition to the app tunnel. A callback request without parameters should return HTTP 400 with missing field state; connection refusal indicates a missing forward. For a completed consent that returns HTTP 400, inspect auth logs for original_url_rejected before changing tunnels. After a fix, restart Connect Google from Command K to obtain fresh state and an authorization code.