Merge pull request #3623 from HeyPuter/juancastro/put-1564-perms-docs-drop-the-app-root-dir-raw-permission-string-wire

🛠️ PUT-1564: Perms docs — drop the app-root-dir raw string, wire the playground examples

src/docs/src/Perms/request.md

@@ -62,10 +62,11 @@ The array form resolves to an array of those values, in the order asked.
 - File system: `fs:{path}:{read|write}`
 - Apps: `apps-of-user:{uuid}:{read|write}`
 - Subdomains: `subdomains-of-user:{uuid}:{read|write}`
-- An app's root directory: `app-root-dir:{app_uid}:{read|write}`
 
 Some permission strings are not supported and are denied silently.
 
+An app's root directory has no raw form: `app-root-dir:` reads as nothing during a permission check, so asking for it this way would prompt on every call and [`check()`](/Perms/check/) would report it as not granted even once it is. Use the `'appRootDir'` resource, which asks the server directly.
+
 A lone string that names no resource is treated as a permission string, so `puter.perms.request('fs:/user/Documents:read')` keeps working.
 
 ## Batching

src/docs/src/examples.js

@@ -193,6 +193,12 @@ const examples = [
                 slug: 'ai-txt2speech-elevenlabs',
                 source: '/playground/examples/ai-txt2speech-elevenlabs.html',
             },
+            {
+                title: 'Text to Speech with Speechify',
+                description: 'Generate speech with Speechify voices using Puter.js AI API. Run and experiment with this TTS example in the playground.',
+                slug: 'ai-txt2speech-speechify',
+                source: '/playground/examples/ai-txt2speech-speechify.html',
+            },
             {
                 title: 'Text to Speech with Gemini',
                 description: 'Generate speech with Gemini voices using Puter.js AI API. Run and experiment with this TTS example in the playground.',
@@ -378,6 +384,30 @@ const examples = [
                 slug: 'fs-delete-directory',
                 source: '/playground/examples/fs-delete-directory.html',
             },
+            {
+                title: 'Share a file',
+                description: 'Share a file with another user using Puter.js filesystem API. Run and experiment with this sharing example in the playground.',
+                slug: 'fs-share',
+                source: '/playground/examples/fs-share.html',
+            },
+            {
+                title: 'Stop sharing a file',
+                description: 'Revoke a share with Puter.js filesystem API. Run and modify this example instantly in your browser.',
+                slug: 'fs-unshare',
+                source: '/playground/examples/fs-unshare.html',
+            },
+            {
+                title: 'List what is shared with you',
+                description: 'List items other people have shared with you using Puter.js filesystem API. Run and experiment with this example in the playground.',
+                slug: 'fs-listShared',
+                source: '/playground/examples/fs-listShared.html',
+            },
+            {
+                title: 'See who a file is shared with',
+                description: 'List the shares on one of your own files with Puter.js filesystem API. Run and modify this example in your browser.',
+                slug: 'fs-getShares',
+                source: '/playground/examples/fs-getShares.html',
+            },
         ],
     },
     {
@@ -713,6 +743,65 @@ const examples = [
                 slug: 'ui-set-menubar',
                 source: '/playground/examples/ui-set-menubar.html',
             },
+            {
+                title: 'Feedback dialog',
+                description: 'Collect feedback with the built-in dialog from the Puter.js UI API. Run and experiment with this example directly in the playground.',
+                slug: 'ui-show-feedback-dialog',
+                source: '/playground/examples/ui-show-feedback-dialog.html',
+            },
+        ],
+    },
+    {
+        title: 'Perms',
+        children: [
+            {
+                title: "Request the user's email",
+                description: "Request access to the user's email address with Puter.js permissions API. Run and experiment with this example directly in the playground.",
+                slug: 'perms-request-email',
+                source: '/playground/examples/perms-request-email.html',
+            },
+            {
+                title: 'Request folder access',
+                description: 'Request write access to a special folder with Puter.js permissions API. Run and modify this example instantly in your browser.',
+                slug: 'perms-request-folder',
+                source: '/playground/examples/perms-request-folder.html',
+            },
+            {
+                title: 'Request several at once',
+                description: 'Request everything your app needs under a single prompt with Puter.js permissions API. Run and experiment with this batch example in the playground.',
+                slug: 'perms-request-batch',
+                source: '/playground/examples/perms-request-batch.html',
+            },
+            {
+                title: 'Check without prompting',
+                description: 'Check whether access is already granted before asking for it with Puter.js permissions API. Run and modify this example in the playground.',
+                slug: 'perms-check',
+                source: '/playground/examples/perms-check.html',
+            },
+            {
+                title: "Request access to the user's apps",
+                description: "Request read access to the user's apps with Puter.js permissions API. Run and experiment with this example directly in the playground.",
+                slug: 'perms-request-apps',
+                source: '/playground/examples/perms-request-apps.html',
+            },
+            {
+                title: "Request access to the user's subdomains",
+                description: "Request write access to the user's subdomains with Puter.js permissions API. Run and modify this example instantly in your browser.",
+                slug: 'perms-request-subdomains',
+                source: '/playground/examples/perms-request-subdomains.html',
+            },
+            {
+                title: "Use another app's data",
+                description: "Request permission to use another app's key-value data with Puter.js permissions API. Run and experiment with this example in the playground.",
+                slug: 'perms-request-app-data',
+                source: '/playground/examples/perms-request-app-data.html',
+            },
+            {
+                title: 'Request a raw permission string',
+                description: 'Request a specific permission string with Puter.js permissions API. Run and modify this example directly in your browser.',
+                slug: 'perms-request-permission',
+                source: '/playground/examples/perms-request-permission.html',
+            },
         ],
     },
     {

src/docs/src/playground/examples/ai-txt2speech-speechify.html

@@ -0,0 +1,19 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="play">Use Speechify voice</button>
+    <script>
+        document.getElementById('play').addEventListener('click', async ()=>{
+            const audio = await puter.ai.txt2speech(
+                "Hello! This sample uses the Speechify Geffen voice.",
+                {
+                    provider: "speechify",
+                    model: "simba-3.2",
+                    voice: "geffen_32"
+                }
+            );
+            audio.play();
+        });
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/fs-getShares.html

@@ -0,0 +1,16 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+            await puter.fs.share('report.txt', 'friend@example.com', 'read');
+
+            const shares = await puter.fs.getShares('report.txt');
+            for (const share of shares) {
+                puter.print(`${share.holder}: ${share.mode} (from ${share.issuer})<br>`);
+            }
+        })()
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/fs-listShared.html

@@ -0,0 +1,14 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            const page = await puter.fs.listShared({ includeTotal: true });
+            puter.print(`About ${page.total} item(s) shared with you<br>`);
+            for (const share of page.items) {
+                puter.print(`${share.path} — ${share.mode} from ${share.issuer}<br>`);
+            }
+        })()
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/fs-share.html

@@ -0,0 +1,15 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            // (1) create a file
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+
+            // (2) share it, read-only
+            const shares = await puter.fs.share('report.txt', 'friend@example.com');
+            puter.print(`Shared with ${shares[0].holder} as ${shares[0].mode}<br>`);
+        })()
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/fs-unshare.html

@@ -0,0 +1,14 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        (async () => {
+            await puter.fs.write('report.txt', 'Quarterly numbers');
+            await puter.fs.share('report.txt', 'friend@example.com');
+
+            const result = await puter.fs.unshare('report.txt', 'friend@example.com');
+            puter.print(`Removed ${result.revoked} share(s)<br>`);
+        })()
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/perms-check.html

@@ -0,0 +1,23 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="save">Save to Documents</button>
+    <script>
+        document.getElementById('save').addEventListener('click', async () => {
+            const details = { name: 'Documents', access: 'write' };
+
+            // check() never prompts, so it can run before deciding whether to.
+            if (await puter.perms.check('folder', details)) {
+                puter.print('Already granted, no prompt needed');
+            } else if (!await puter.perms.request('folder', details)) {
+                puter.print('Documents write access denied');
+                return;
+            }
+
+            const user = await puter.auth.getUser();
+            await puter.fs.write(`/${user.username}/Documents/notes.txt`, 'Saved!');
+            puter.print('Saved to Documents');
+        });
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/perms-request-batch.html

@@ -0,0 +1,20 @@
+<html>
+<body>
+    <script src="https://js.puter.com/v2/"></script>
+    <button id="setup">Set Up</button>
+    <script>
+        document.getElementById('setup').addEventListener('click', async () => {
+            // One prompt for the set; the dialog lists only what is missing.
+            const [documents, apps, email] = await puter.perms.request([
+                { resource: 'folder', name: 'Documents', access: 'write' },
+                { resource: 'apps' },
+                { resource: 'email' },
+            ]);
+
+            puter.print(`Documents: ${documents ?? 'denied'}`);
+            puter.print(`Apps: ${apps ? 'granted' : 'denied'}`);
+            puter.print(`Email: ${email ?? 'denied'}`);
+        });
+    </script>
+</body>
+</html>

src/docs/src/playground/examples/ui-show-feedback-dialog.html

@@ -0,0 +1,14 @@
+<html>
+<body>
+    <button id="feedback">Send us feedback</button>
+    <script src="https://js.puter.com/v2/"></script>
+    <script>
+        document.getElementById('feedback').addEventListener('click', async () => {
+            const sent = await puter.ui.showFeedbackDialog();
+            if (sent) {
+                puter.print('Thanks for your feedback!');
+            }
+        });
+    </script>
+</body>
+</html>

src/docs/src/redirects.js

@@ -1,5 +1,25 @@
 const redirects = {
     '/Introduction': '/',
+
+    // `puter.perms` collapsed one-method-per-task into `request(resource,
+    // details)`, so these pages went. Every one of them shipped, which is the
+    // reason for the redirect: an external link or a bookmark would otherwise
+    // land on nothing. Pages that only ever existed on the branch that removed
+    // them are deliberately absent — nobody could have a link to those.
+    '/Perms/requestAppData': '/Perms/appData',
+    '/Perms/requestEmail': '/Perms/request',
+    '/Perms/requestManageApps': '/Perms/request',
+    '/Perms/requestManageSubdomains': '/Perms/request',
+    '/Perms/requestReadApps': '/Perms/request',
+    '/Perms/requestReadDesktop': '/Perms/request',
+    '/Perms/requestReadDocuments': '/Perms/request',
+    '/Perms/requestReadPictures': '/Perms/request',
+    '/Perms/requestReadSubdomains': '/Perms/request',
+    '/Perms/requestReadVideos': '/Perms/request',
+    '/Perms/requestWriteDesktop': '/Perms/request',
+    '/Perms/requestWriteDocuments': '/Perms/request',
+    '/Perms/requestWritePictures': '/Perms/request',
+    '/Perms/requestWriteVideos': '/Perms/request',
 };
 
 module.exports = redirects;