tempest-react-sdk 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",
@@ -25,11 +25,13 @@
     "dist",
     "bin",
     "template",
+    "template-pwa",
     "README.md",
     "LICENSE"
   ],
   "bin": {
-    "create-tempest-app": "./bin/create-tempest-app.mjs"
+    "create-tempest-app": "./bin/create-tempest-app.mjs",
+    "tempest": "./bin/tempest.mjs"
   },
   "main": "./dist/tempest-react-sdk.cjs",
   "module": "./dist/tempest-react-sdk.js",
@@ -53,6 +55,11 @@
       "import": "./dist/vite.js",
       "require": "./dist/vite.cjs"
     },
+    "./sw": {
+      "types": "./dist/sw.d.ts",
+      "import": "./dist/sw.js",
+      "require": "./dist/sw.cjs"
+    },
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
@@ -68,6 +75,7 @@
     "test:coverage": "vitest run --coverage",
     "clean": "rm -rf dist coverage",
     "size": "size-limit",
+    "docs:llms": "node scripts/gen-llms.mjs",
     "prepare": "husky",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run test:run && npm run build"
   },

package/template/_prettierrc.json

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "printWidth": 100,
+  "trailingComma": "all",
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/template/eslint.config.js

@@ -2,6 +2,8 @@ import js from "@eslint/js";
 import globals from "globals";
 import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+import unusedImports from "eslint-plugin-unused-imports";
 import tseslint from "typescript-eslint";
 
 export default tseslint.config(
@@ -16,12 +18,27 @@ export default tseslint.config(
         plugins: {
             "react-hooks": reactHooks,
             "react-refresh": reactRefresh,
+            "simple-import-sort": simpleImportSort,
+            "unused-imports": unusedImports,
         },
         rules: {
             ...reactHooks.configs.recommended.rules,
             "react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
             "@typescript-eslint/consistent-type-imports": "error",
-            "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+            // Organize imports/exports (tempest fix).
+            "simple-import-sort/imports": "error",
+            "simple-import-sort/exports": "error",
+            // Remove dead imports + flag unused vars (tempest fix).
+            "@typescript-eslint/no-unused-vars": "off",
+            "unused-imports/no-unused-imports": "error",
+            "unused-imports/no-unused-vars": [
+                "warn",
+                { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+            ],
+            // Tidy whitespace (tempest fix).
+            "no-multiple-empty-lines": ["error", { max: 1, maxEOF: 0, maxBOF: 0 }],
+            "no-trailing-spaces": "error",
+            "eol-last": ["error", "always"],
         },
     },
 );

package/template/package.json

@@ -9,7 +9,10 @@
     "preview": "vite preview",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
-    "lint:fix": "eslint . --fix"
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "fix": "tempest fix",
+    "doctor": "tempest doctor"
   },
   "dependencies": {
     "react": "^19.0.0",
@@ -24,7 +27,10 @@
     "eslint": "^9.36.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.22",
+    "eslint-plugin-simple-import-sort": "^12.1.0",
+    "eslint-plugin-unused-imports": "^4.1.4",
     "globals": "^16.0.0",
+    "prettier": "^3.8.0",
     "typescript": "~5.9.0",
     "typescript-eslint": "^8.45.0",
     "vite": "^7.0.0"

package/template-pwa/README.md

@@ -0,0 +1,64 @@
+# Tempest App (PWA)
+
+Scaffolded with [`create-tempest-app --pwa`](https://www.npmjs.com/package/tempest-react-sdk) and powered by [`tempest-react-sdk`](https://www.npmjs.com/package/tempest-react-sdk).
+
+## Stack
+
+- **Vite** with the `@` → `src` alias (`tempest-react-sdk/vite` → `createViteConfig`)
+- **React Router v7** declarative routing (`defineRoutes` + `<AppRouter>`)
+- **Zustand** state (`createAuthStore` + `createSelectors`)
+- **TanStack Query** cache (mounted by `<AppProviders>`)
+- **PWA**: installable manifest + a service worker built from `tempest-react-sdk/sw`, with web-push wiring
+
+## Getting started
+
+```bash
+npm install
+cp .env.example .env   # adjust VITE_API_URL + VITE_VAPID_PUBLIC_KEY
+npm run dev            # http://127.0.0.1:5173
+```
+
+## PWA layout
+
+```text
+public/manifest.webmanifest   # install metadata (name, icons, theme color)
+public/icon.svg               # app icon (replace with your brand; PNG 192/512 recommended)
+src/sw.ts                     # service worker — push + notificationclick + skip-waiting
+vite.sw.config.ts             # bundles src/sw.ts → dist/sw.js (classic worker)
+index.html                    # manifest link + theme-color + apple meta tags
+src/main.tsx                  # registers /sw.js in production, cleans up SW in dev
+src/pages/Dashboard.tsx       # Install button + push notifications toggle
+```
+
+## How it works
+
+- **Install**: `index.html` links the manifest; `useBeforeInstallPrompt` (in
+  `Dashboard.tsx`) surfaces a custom Install button when the browser offers one.
+- **Service worker**: `src/sw.ts` imports `installPushHandler`,
+  `installNotificationClickHandler` and `installSkipWaitingListener` from
+  `tempest-react-sdk/sw`. `npm run build` bundles it to `dist/sw.js` via
+  `vite.sw.config.ts`, and `src/main.tsx` registers it in production.
+- **Web push**: `usePushSubscription` reads `VITE_VAPID_PUBLIC_KEY`, subscribes
+  through the active service worker, and hands the subscription to your
+  `onSubscribe` callback to POST to your backend.
+
+> ⚠️ The service worker is bundled at **build time**, so push and offline behave
+> only in a production build. Test them with:
+>
+> ```bash
+> npm run build && npm run preview
+> ```
+>
+> In `npm run dev` the worker is intentionally unregistered to avoid stale caches.
+
+## Replace the icons
+
+`public/icon.svg` is a placeholder. For guaranteed installability across all
+browsers, add PNG icons (192×192 and 512×512) to `public/` and point the
+`manifest.webmanifest` `icons` entries at them.
+
+## Next steps
+
+- Add a route: drop a page in `src/pages/` and an entry in `src/routes.tsx`.
+- Fetch data: `useQuery({ queryKey: queryKeys.me(), queryFn: () => api.get("/me") })`.
+- Generate VAPID keys on your backend and set `VITE_VAPID_PUBLIC_KEY` in `.env`.

package/template-pwa/_env.example

@@ -0,0 +1,7 @@
+# Base URL of your backend API (consumed by src/lib/api.ts).
+VITE_API_URL=http://127.0.0.1:8000
+
+# VAPID public key for web push (consumed by usePushSubscription in
+# src/pages/Dashboard.tsx). Generate a key pair on your backend; the private
+# half stays on the server, this public half ships to the browser.
+VITE_VAPID_PUBLIC_KEY=

package/template-pwa/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="pt-BR">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/svg+xml" href="/icon.svg" />
+        <link rel="apple-touch-icon" href="/icon.svg" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+        <meta name="theme-color" content="#0b1a36" />
+        <meta name="description" content="App React fiado com tempest-react-sdk." />
+        <meta name="application-name" content="Tempest App" />
+        <meta name="apple-mobile-web-app-capable" content="yes" />
+        <meta name="apple-mobile-web-app-title" content="Tempest App" />
+        <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />
+        <meta name="mobile-web-app-capable" content="yes" />
+        <link rel="manifest" href="/manifest.webmanifest" />
+        <title>Tempest App</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

package/template-pwa/package.json

@@ -0,0 +1,6 @@
+{
+  "scripts": {
+    "build": "tsc --noEmit && vite build && npm run build:sw",
+    "build:sw": "vite build --config vite.sw.config.ts"
+  }
+}

package/template-pwa/public/icon-maskable.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Tempest">
+    <rect width="512" height="512" fill="#0b1a36" />
+    <path d="M176 200h160l-30 50h-54v140l-46 24V250h-54z" fill="#ffffff" />
+</svg>

package/template-pwa/public/icon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" role="img" aria-label="Tempest">
+    <rect width="512" height="512" rx="96" fill="#0b1a36" />
+    <path d="M152 168h208l-40 64h-72v176l-64 32V232h-72z" fill="#ffffff" />
+</svg>

package/template-pwa/public/manifest.webmanifest

@@ -0,0 +1,35 @@
+{
+    "name": "Tempest App",
+    "short_name": "Tempest",
+    "description": "App React fiado com tempest-react-sdk.",
+    "id": "/",
+    "start_url": "/?source=pwa",
+    "scope": "/",
+    "display": "standalone",
+    "orientation": "portrait",
+    "lang": "pt-BR",
+    "dir": "ltr",
+    "background_color": "#ffffff",
+    "theme_color": "#0b1a36",
+    "categories": ["productivity", "utilities"],
+    "icons": [
+        {
+            "src": "/icon.svg",
+            "sizes": "192x192",
+            "type": "image/svg+xml",
+            "purpose": "any"
+        },
+        {
+            "src": "/icon.svg",
+            "sizes": "512x512",
+            "type": "image/svg+xml",
+            "purpose": "any"
+        },
+        {
+            "src": "/icon-maskable.svg",
+            "sizes": "512x512",
+            "type": "image/svg+xml",
+            "purpose": "maskable"
+        }
+    ]
+}

package/template-pwa/src/main.tsx

@@ -0,0 +1,36 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { registerServiceWorker, skipWaiting } from "tempest-react-sdk";
+import "tempest-react-sdk/styles.css";
+import { App } from "@/App";
+
+createRoot(document.getElementById("root")!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>,
+);
+
+// The service worker is bundled to `/sw.js` at build time, so it only exists in
+// production. In dev we proactively unregister any leftover worker to avoid a
+// stale cache shadowing your `npm run dev` output.
+if (import.meta.env.DEV && "serviceWorker" in navigator) {
+    void navigator.serviceWorker
+        .getRegistrations()
+        .then((regs) => Promise.all(regs.map((r) => r.unregister())))
+        .catch((err) => console.warn("[sw] dev cleanup failed", err));
+}
+
+if (import.meta.env.PROD) {
+    void registerServiceWorker({
+        url: "/sw.js",
+        onUpdate: (waiting) => {
+            // A new worker is ready. Prompt your users however you like; here we
+            // just activate it and reload so the next visit is up to date.
+            if (confirm("Nova versão disponível. Atualizar agora?")) {
+                skipWaiting(waiting);
+                window.location.reload();
+            }
+        },
+        onError: (err) => console.warn("[sw] registration failed", err),
+    });
+}

package/template-pwa/src/pages/Dashboard.tsx

@@ -0,0 +1,73 @@
+import { Button, useBeforeInstallPrompt, usePushSubscription } from "tempest-react-sdk";
+import { useAuth } from "@/stores/auth";
+
+/**
+ * Protected page (see the `guard` in src/routes.tsx). Lazy-loaded, so it is
+ * code-split into its own chunk. Default export because `lazy` expects one.
+ *
+ * Adds two PWA controls:
+ *  - Install button (`useBeforeInstallPrompt`) — appears only when the browser
+ *    offers an install prompt and the app is not yet installed.
+ *  - Push toggle (`usePushSubscription`) — subscribes/unsubscribes to web push.
+ *    The service worker must be active, so this works in a production build
+ *    (`npm run build && npm run preview`), not in `npm run dev`.
+ */
+export default function Dashboard() {
+    const user = useAuth.use.user();
+    const install = useBeforeInstallPrompt();
+
+    const push = usePushSubscription({
+        vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY ?? "",
+        onSubscribe: async (subscription) => {
+            // Send the subscription to your backend so it can deliver pushes.
+            // await api.post("/webpush/subscribe", { body: subscription });
+            console.log("push subscription", subscription);
+        },
+        onUnsubscribe: async () => {
+            // await api.delete("/webpush/my");
+            console.log("push unsubscribed");
+        },
+    });
+
+    return (
+        <section>
+            <h1>Dashboard</h1>
+            <p>
+                Signed in as <strong>{user?.name}</strong> ({user?.email}).
+            </p>
+            <p>This route is only reachable while authenticated.</p>
+
+            <h2>PWA</h2>
+
+            {install.installed ? (
+                <p>✅ App installed.</p>
+            ) : install.installable ? (
+                <Button onClick={() => void install.prompt()}>Install app</Button>
+            ) : (
+                <p>Install prompt not available in this browser/context.</p>
+            )}
+
+            <h2>Notifications</h2>
+
+            {!push.supported ? (
+                <p>Web push is not supported here (needs HTTPS + an active service worker).</p>
+            ) : (
+                <>
+                    <Button
+                        onClick={() =>
+                            void (push.subscribed ? push.unsubscribe() : push.subscribe())
+                        }
+                        disabled={push.loading}
+                    >
+                        {push.subscribed ? "Disable notifications" : "Enable notifications"}
+                    </Button>
+                    <p>
+                        Permission: <strong>{push.permission}</strong> · Subscribed:{" "}
+                        <strong>{String(push.subscribed)}</strong>
+                    </p>
+                    {push.error && <p style={{ color: "crimson" }}>{push.error.message}</p>}
+                </>
+            )}
+        </section>
+    );
+}

package/template-pwa/src/sw.ts

@@ -0,0 +1,35 @@
+/// <reference lib="webworker" />
+import {
+    installNotificationClickHandler,
+    installPushHandler,
+    installSkipWaitingListener,
+} from "tempest-react-sdk/sw";
+
+/**
+ * Service worker. Bundled to `dist/sw.js` by `vite.sw.config.ts` (see the
+ * `build:sw` script) and registered from `src/main.tsx`.
+ *
+ * The three SDK helpers wire the boilerplate:
+ *  - `installPushHandler` parses the `push` payload (JSON, plain-text fallback)
+ *    and shows a notification.
+ *  - `installNotificationClickHandler` focuses an open tab on click, or opens a
+ *    new one at the payload's `url`.
+ *  - `installSkipWaitingListener` activates a waiting worker when the page posts
+ *    `{ type: "SKIP_WAITING" }` (paired with `registerServiceWorker`'s
+ *    `onUpdate` in `main.tsx`).
+ */
+declare const self: ServiceWorkerGlobalScope;
+
+installPushHandler({
+    defaultTitle: "Notificação",
+    defaultIcon: "/icon.svg",
+    defaultBadge: "/icon.svg",
+});
+
+installNotificationClickHandler();
+installSkipWaitingListener();
+
+// Take control of open pages as soon as this worker activates.
+self.addEventListener("activate", (event) => {
+    event.waitUntil(self.clients.claim());
+});

package/template-pwa/src/vite-env.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+    /** Base URL of the backend API (src/lib/api.ts). */
+    readonly VITE_API_URL?: string;
+    /** VAPID public key for web push (src/pages/Dashboard.tsx). */
+    readonly VITE_VAPID_PUBLIC_KEY?: string;
+}
+
+interface ImportMeta {
+    readonly env: ImportMetaEnv;
+}

package/template-pwa/vite.sw.config.ts

@@ -0,0 +1,27 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+
+/**
+ * Standalone build that bundles `src/sw.ts` (and the `tempest-react-sdk/sw`
+ * helpers it imports) into a single classic service worker at `dist/sw.js`.
+ *
+ * Run after the app build via the `build:sw` script — `emptyOutDir: false`
+ * keeps the app's `dist/` intact. The IIFE format produces a worker with no
+ * `import`/`export` tokens, so it registers as a classic worker (no
+ * `type: "module"` needed).
+ */
+export default defineConfig({
+    build: {
+        emptyOutDir: false,
+        sourcemap: true,
+        lib: {
+            entry: resolve(__dirname, "src/sw.ts"),
+            formats: ["iife"],
+            name: "sw",
+            fileName: () => "sw.js",
+        },
+        rollupOptions: {
+            output: { entryFileNames: "sw.js", inlineDynamicImports: true },
+        },
+    },
+});