@vibes.diy/prompts 14.3.175 → 14.3.176

package/llms/youtube.md

@@ -18,26 +18,37 @@ developer console to mint one: that is the flow connections exists to replace.
 The console trip below is for the **owner** of this app, once, and for nobody
 else.
 
-## 1. Bring your own key, and explain how
-
-The owner gets a key from Google, once:
-
-1. Open the Google Cloud console and create or select a project.
-2. Go to APIs & Services, then Library, and enable **YouTube Data API v3**.
-3. Go to Credentials, then Create credentials, then API key.
-4. Restrict the key to the YouTube Data API v3.
-5. Set it on the vibe as `YOUTUBE_API_KEY` — the vibe's settings page, or
-   `vibes-diy secrets set YOUTUBE_API_KEY <the key>`.
-
-The app carries those five steps in its own UI, because the person reading them
-is the person who has to do them.
-
-When the key is missing, the app shows the owner the setup steps for a YouTube Data API v3 key instead of an error.
-
-The backend answers `{ ok: false, reason: "missing-key" }` when
-`ctx.secrets.YOUTUBE_API_KEY` is absent, and the client renders the numbered
-steps, naming "YouTube Data API v3" and `YOUTUBE_API_KEY` in so many words so
-the owner knows what to enable and what to call it.
+## 1. The setup item: the owner's YouTube Data API key
+
+The owner gets a key from Google, once. The Setup surface the item lands on —
+the owner-only entry in the app's navigation, the verdict from `/setup`, the
+re-read on focus that unlocks the dashboard in place — is the use-vibe docs'
+*Some apps need setup before they work*; this recipe contributes one item to
+it. The YouTube item is the API key: the backend answers missing-key while ctx.secrets.YOUTUBE_API_KEY is absent, and its steps link the Google Cloud console's YouTube Data API v3 library page and its Credentials page by URL and name YOUTUBE_API_KEY in so many words.
+The steps are written for someone who has never opened the console, so each
+one is a link to the exact page and uses the words that page uses:
+
+1. Open the **YouTube Data API v3** page in the Google Cloud console:
+   <https://console.cloud.google.com/apis/library/youtube.googleapis.com>
+   (sign in with a Google account; create a project when it asks) and press
+   **Enable**.
+2. Open **Credentials**: <https://console.cloud.google.com/apis/credentials>.
+   Press **Create credentials**, choose **API key**, and copy the key. Then
+   open the key, and under **API restrictions** choose **Restrict key**, tick
+   **YouTube Data API v3**, and save.
+3. Open this vibe's **Settings** tab on vibes.diy:
+   `https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` (that is
+   **My Vibes** → this vibe → **Settings**). Under **Secrets**, enter the key
+   `YOUTUBE_API_KEY`, paste the value, and save. From a terminal the same
+   thing is `npx vibes-diy secrets set YOUTUBE_API_KEY --vibe <ownerHandle>/<appSlug>`.
+4. Come back to the app. The dashboard works the moment the key is saved; no
+   redeploy.
+
+Those steps are the item's copy on the Setup surface, with the vibe's real
+handle and slug filled in from the `ownerHandle` and `appSlug` the `/setup`
+route hands over. In the consumer flow, a dashboard whose key is not set
+reads *Channel stats are not open yet*; the owner's Setup entry is where the
+steps are, and later it is where a rotated key goes.
 
 Only the owner can set or rotate a secret, and handlers see the current value on
 every invocation — so the dashboard starts working the moment the key lands, with
@@ -241,7 +252,8 @@ Google answers a refusal with `error.errors[0].reason`. Classify on it and pass
 the reason through:
 
 - `quotaExceeded` — "Daily quota used; resets at midnight Pacific."
-- `keyInvalid` or `API_KEY_INVALID` — show the setup steps from section 1 again.
+- `keyInvalid` or `API_KEY_INVALID` — say so, and point the owner at the Setup
+  entry: the item reads *Done* because a value is present, and the value is wrong.
 - `accessNotConfigured` — "Enable YouTube Data API v3 on this key's project."
 - anything else — show the API's own `error.message`.
 
@@ -399,6 +411,15 @@ export async function fetch(request, ctx) {
 
   const isOwner = ctx.userInfo?.userHandle != null && ctx.userInfo.userHandle === ctx.appInfo.ownerHandle;
 
+  // The setup verdict: ready for everyone, the item (and the handle + slug the Setup screen links
+  // with) for the owner alone. No live call, so it sits in front of the owner gate.
+  if (url.pathname === "/setup") {
+    const items = [{ id: "youtube-key", label: "YouTube Data API v3 key", done: Boolean(ctx.secrets.YOUTUBE_API_KEY) }];
+    const ready = items.every((item) => item.done);
+    if (isOwner) return json({ ok: true, ready, owner: isOwner, items, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+    return json({ ok: true, ready, owner: isOwner });
+  }
+
   // Anyone who is not the owner is answered from what the tick already stored, and the channel they
   // asked for is resolved against the tracked docs' aliases. Nothing here reaches googleapis.com, so
   // a stranger with a refresh button cannot spend the owner's daily quota.
@@ -510,25 +531,76 @@ export async function scheduled(event, ctx) {
 
 ### `App.jsx`
 ```jsx app=youtube-dashboard
-import React, { useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { useFireproof } from "use-fireproof";
-import { Button, Field, Input, Row } from "@vibes.diy/pouf";
+import { apiFetch } from "use-vibes";
+import { Badge, Button, Field, Heading, Input, Row, Stack, Text } from "@vibes.diy/pouf";
+
+// The setup verdict, read on mount and again whenever the app comes back into view: the owner
+// sets the key in another tab and returns, and the dashboard unlocks without a reload.
+function useSetup() {
+  const [setup, setSetup] = useState(null); // { ready, owner, items?, ownerHandle?, appSlug? }
+  const latest = useRef(0);
+  useEffect(() => {
+    // Mount, focus and visibility reads overlap; only the latest one may land, or a slow stale
+    // answer overwrites a fresh one.
+    const load = () => {
+      const n = ++latest.current;
+      apiFetch("/setup").then((r) => r.json()).catch(() => ({ ready: false, owner: false })).then((s) => { if (n === latest.current) setSetup(s); });
+    };
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
+  }, []);
+  return setup;
+}
 
-const SETUP_STEPS = [
-  "Open the Google Cloud console and create or select a project.",
-  "In APIs & Services, enable YouTube Data API v3.",
-  "In Credentials, create an API key and restrict it to YouTube Data API v3.",
-  "Set it on this vibe as YOUTUBE_API_KEY in the settings page.",
-];
+// The Setup surface, the owner's alone: one item, every step a link to the exact page in that
+// page's own words, with this vibe's real handle and slug filled in.
+function SetupScreen({ setup }) {
+  const vibe = `${setup.ownerHandle}/${setup.appSlug}`;
+  const settingsUrl = `https://vibes.diy/vibes/mine/${vibe}/settings`;
+  const key = setup.items.find((item) => item.id === "youtube-key");
+  return (
+    <Stack>
+      <Heading>Setup</Heading>
+      <Row gap={2}>
+        <Text>{key.label}</Text>
+        <Badge tone={key.done ? "up" : "info"}>{key.done ? "Done" : "To do"}</Badge>
+      </Row>
+      <ol>
+        <li>
+          Open the <a href="https://console.cloud.google.com/apis/library/youtube.googleapis.com" target="_blank" rel="noreferrer">YouTube Data API v3 page</a> in the Google Cloud console
+          (use your Google account; create a project when it asks) and press <b>Enable</b>.
+        </li>
+        <li>
+          Open <a href="https://console.cloud.google.com/apis/credentials" target="_blank" rel="noreferrer">Credentials</a>, press <b>Create credentials</b>, choose <b>API key</b>, and copy it.
+          Then open the key, and under <b>API restrictions</b> choose <b>Restrict key</b>, tick <b>YouTube Data API v3</b>, and save.
+        </li>
+        <li>
+          Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
+          Under <b>Secrets</b>, enter the key <code>YOUTUBE_API_KEY</code>, paste the value, and save.
+          From a terminal instead: <code>npx vibes-diy secrets set YOUTUBE_API_KEY --vibe {vibe}</code>.
+        </li>
+        <li>Come back here: the dashboard works as soon as the key is saved. The key stays on the server.</li>
+      </ol>
+    </Stack>
+  );
+}
 
 export default function App() {
   const { useLiveQuery, database } = useFireproof("youtube");
   const { docs: snapshots } = useLiveQuery("type", { key: "snapshot" });
+  const setup = useSetup();
+  const [screen, setScreen] = useState("dashboard");
   const [input, setInput] = useState("");
   const [channel, setChannel] = useState(null);
   const [problem, setProblem] = useState(null);
   const [source, setSource] = useState(null);
   const [asOf, setAsOf] = useState(null);
+  const ready = setup?.ready === true;
 
   const connect = async () => {
     const res = await fetch(`/_api/channel?q=${encodeURIComponent(input)}`);
@@ -552,46 +624,55 @@ export default function App() {
   const history = snapshots.slice().sort((a, b) => a.day.localeCompare(b.day));
 
   return (
-    <div>
-      <Row gap={2} align="top">
-        <Field label="Channel">{(id, describedBy) => <Input id={id} describedBy={describedBy} value={input} onChange={setInput} placeholder="@handle or channel URL" />}</Field>
-        <Button type="button" onClick={connect}>Connect channel</Button>
+    <Stack>
+      <Row gap={2}>
+        <Button variant="quiet" onClick={() => setScreen("dashboard")}>Dashboard</Button>
+        {/* The Setup entry: the owner's alone, highlighted while the item is still to do, quiet once done. */}
+        {setup?.owner && (
+          <Button variant={ready ? "quiet" : "solid"} onClick={() => setScreen("setup")}>
+            Setup{ready ? "" : " · to do"}
+          </Button>
+        )}
       </Row>
 
-      {problem?.reason === "missing-key" && (
-        <section>
-          <h2>Add a YouTube Data API v3 key</h2>
-          <ol>
-            {SETUP_STEPS.map((step) => (
-              <li key={step}>{step}</li>
-            ))}
-          </ol>
-          <p>The key is stored as YOUTUBE_API_KEY and stays on the server.</p>
-        </section>
-      )}
-      {problem?.reason === "no-snapshot-yet" && <p>The first daily snapshot has not been saved yet.</p>}
-      {problem && !["missing-key", "no-snapshot-yet"].includes(problem.reason) && <p role="alert">{problem.message}</p>}
-
-      {channel && (
-        <section>
-          <h2>{channel.title}</h2>
-          <p>{channel.subscribersHidden ? "Subscribers hidden by the channel" : `${channel.subscribers} subscribers`}</p>
-          <small>YouTube rounds public subscriber counts.</small>
-          <p>{channel.views} total views across {channel.videoCount} videos</p>
-          {source === "snapshot" && <small>As of {asOf} — live numbers are refreshed for the channel owner.</small>}
-        </section>
+      {screen === "setup" && setup?.owner ? (
+        <SetupScreen setup={setup} />
+      ) : (
+        <Stack>
+          {ready ? (
+            <Row gap={2} align="top">
+              <Field label="Channel">{(id, describedBy) => <Input id={id} describedBy={describedBy} value={input} onChange={setInput} placeholder="@handle or channel URL" />}</Field>
+              <Button type="button" onClick={connect}>Connect channel</Button>
+            </Row>
+          ) : (
+            <Text muted>Channel stats are not open yet.</Text>
+          )}
+
+          {problem?.reason === "no-snapshot-yet" && <Text>The first daily snapshot has not been saved yet.</Text>}
+          {problem && problem.reason !== "no-snapshot-yet" && <Text role="alert">{problem.message}</Text>}
+
+          {channel && (
+            <section>
+              <h2>{channel.title}</h2>
+              <p>{channel.subscribersHidden ? "Subscribers hidden by the channel" : `${channel.subscribers} subscribers`}</p>
+              <small>YouTube rounds public subscriber counts.</small>
+              <p>{channel.views} total views across {channel.videoCount} videos</p>
+              {source === "snapshot" && <small>As of {asOf} — live numbers are refreshed for the channel owner.</small>}
+            </section>
+          )}
+
+          <section>
+            <h3>Not available with an API key</h3>
+            <p>Watch time, revenue, impressions, traffic sources and demographics come from YouTube Analytics with OAuth.</p>
+          </section>
+
+          <section>
+            <h3>Daily snapshots</h3>
+            {history.length === 0 ? <p>First snapshot saves within the hour.</p> : <Chart rows={history} />}
+          </section>
+        </Stack>
       )}
-
-      <section>
-        <h3>Not available with an API key</h3>
-        <p>Watch time, revenue, impressions, traffic sources and demographics come from YouTube Analytics with OAuth.</p>
-      </section>
-
-      <section>
-        <h3>Daily snapshots</h3>
-        {history.length === 0 ? <p>First snapshot saves within the hour.</p> : <Chart rows={history} />}
-      </section>
-    </div>
+    </Stack>
   );
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.175",
+  "version": "14.3.176",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -39,10 +39,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/api-types": "14.3.175",
-    "@vibes.diy/call-ai-v2": "14.3.175",
-    "@vibes.diy/identity": "14.3.175",
-    "@vibes.diy/use-vibes-types": "14.3.175",
+    "@vibes.diy/api-types": "14.3.176",
+    "@vibes.diy/call-ai-v2": "14.3.176",
+    "@vibes.diy/identity": "14.3.176",
+    "@vibes.diy/use-vibes-types": "14.3.176",
     "arktype": "~2.2.8",
     "json-schema-faker": "~0.6.3"
   },