feat(toolkit-examples): dmail and web3mail integration guide

[Nkovaturient]

Description

• addresses sub-issue Documentation & Examples Site for storacha console toolkit #5

Dmail Integration + Web3Mail Integration

integration-guide folder encompasses Auth , Space Suite, and Upload Tool integration in dmail and web3mail services

• simple dapp demonstarting Storacha Toolkit's Auth Component ( useStorachaAuth and StorachaAuth), Space Suites, and Upload Tool integration examples site
• Simplified import paths for easier local development

Both examples now demonstrate proper integration of Storacha Console Toolkit components with clear separation of concerns and improved developer experience.

---

[Nkovaturient]

@travis @Dhruv-Varshney-developer kindly review it.

[Nkovaturient]

• Streamlined auth flow and improvised working of StorachaAuth in web3mail example demo

Note: When clicking the email verification link in Ethermail, one may encounter this error:

Blocked form submission to 'https://up.storacha.network/validate-email?ucan=...' 
because the form's frame is sandboxed and the 'allow-forms' permission is not set.

Root Cause

1. Ethermail's Email Viewer: Ethermail displays emails in a sandboxed iframe for security
2. Sandbox Restrictions: The iframe doesn't have the allow-forms permission
3. Form Submission: The validation page at up.storacha.network/validate-email attempts to submit a form
4. Browser Block: The browser blocks the form submission due to sandbox restrictions

Workarounds

Right-Click and Open in New Tab

1. In your Ethermail inbox, right-click the "Verify email address" button
2. Select "Open link in new tab"
3. This opens the validation page in a new window without iframe sandbox restrictions and StorachaAuth validates the email address succesfully

web3MailAuth.Demo.mov

Long term solution

?? The validation page at up.storacha.network/validate-email should be updated to Detect iframe context and automatically redirect to a new window ??

[Dhruv-Varshney-developer]

Thanks for the work here @Nkovaturient !
Assigning @alikhere for reviews here.
Feel free to skip our team's review of individual PRs on this project.
Please review PRs among yourselves.
Feel free to tag me around if there's a major update or a blocker here.

[Nkovaturient]

@alikhere Kindly review it on these latest changes.

packages/react/src/components/upload/UploadTool.tsx:

• fixed hook-order bug in UploadToolTypeSelector (hook before conditional), removed duplicate setUploadType, added stable keys when using renderOption to silence React warnings.

Web3Mail & Dmail:

• added UploadTool UI and Space Suite components to showcase their workings and integration process in above services.
• integrated quick upload + advanced upload trigger

Space creation UI	Upload Tool

To Fix:

Provider err after new Private/Public Space addition	Invocation err while uploading

[alikhere]

Following issues that still need to be addressed:

1:
failed provisioning space: did:key:... with provider: did:web:storacha.network.
The space may not be saved before provisioning, or the account may not be fully initialized.

2:
failed space/blob/add invocation while uploading files
The selected space is not set as the current space in the client, or the space object being used is stale.

3:
Sharing functionality not working

All of these functions are working correctly in the examples/space-management example (you can run locally), which you can refer it for guidance and fix the issue.

[alikhere]

Hey @Nkovaturient , I’ve added some required changes to the review. Please check them whenever you have time. Thanks for your work on this.

[Nkovaturient]

Hey @alikhere

• updated README.md, tsconfig for integration-guide and also found the root cause of provision and upload issues:

Findings:-

failed provisioning space and upload err is caused due to EtherMail and dmail services account which needs to have a account plan(starter or so) to have the space provisioned and further avoid space/blob/add ucan invocation issues.

• it works for normal @gmail.com addr without any billing setup, but web3mail and dmail services needs to have Account billing plan to proceed further.

• Same issues were raised in examples/space-management while authorizing with @ethmail.cc addr:

space-management.1.mov

Solution Proposed:

• When space provisioning fails with AccountPlanMissing, --> then proceed to show a message explaining the free Starter plan is available, --> Offers to open the billing/plan selection page, --> User can select the free plan and retry

[alikhere]

@Nkovaturient
Thanks for the detailed analysis. One possible approach is to introduce a PlanGate component in the toolkit that checks the user’s plan before allowing the creation of their first space,, similar to how the Storacha console handles it, If you have a idea or alternative approach, I’m open for it.