create-nscope-app 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nscope-app",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Scaffold a Nscope client app (Vite or Next.js)",
   "type": "module",
   "bin": {
@@ -19,4 +19,4 @@
   ],
   "license": "ISC",
   "author": "Traton Digital"
-}
+}

package/templates/next/.env.local.example

@@ -1,3 +1,5 @@
 NEXT_PUBLIC_NSCOPE_API_KEY={{API_KEY}}
-NEXT_PUBLIC_NSCOPE_BASE_URL={{BASE_URL}}
 NEXT_PUBLIC_NSCOPE_REDIRECT_URI={{REDIRECT_URI}}
+
+# Referência local — a URL da API é definida no build do pacote @nscope/sdk
+# NEXT_PUBLIC_NSCOPE_BASE_URL={{BASE_URL}}

package/templates/next/README.md

@@ -15,6 +15,12 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000).
 
+## How it works
+
+- `lib/nscope.ts` exports `nscopeConfig` for `NscopeProvider`.
+- `Providers` wraps the app with `loadingFallback` while the session initializes.
+- `HomePage` uses `useNscope()` — `authenticated`, `customer`, `login`, `logout`, and `<Can>`.
+
 ## Next steps
 
 - Wrap protected pages with `<GuardedRoute>`

package/templates/next/app/globals.css

@@ -19,6 +19,18 @@ body {
   padding: 0 1rem;
 }
 
+.muted {
+  color: #71717a;
+  font-size: 0.95rem;
+}
+
+code {
+  font-size: 0.9em;
+  background: #f4f4f5;
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
+}
+
 button {
   border: none;
   border-radius: 8px;

package/templates/next/components/home-page.tsx

@@ -3,37 +3,48 @@
 import { Can, useNscope } from "@nscope/react";
 
 export function HomePage() {
-  const { user, isAuthenticated, isLoading, login, logout } = useNscope();
-
-  if (isLoading) {
-    return <main className="page">Loading…</main>;
-  }
+  const { authenticated, customer, login, logout } = useNscope();
 
   return (
     <main className="page">
       <h1>{{PROJECT_NAME}}</h1>
 
-      {isAuthenticated && user ? (
+      {authenticated && customer ? (
         <>
-          <p>Signed in as {user.name ?? user.email}</p>
-          <Can subject="users" action="LIST">
-            <p>You can list users.</p>
+          <p>
+            Signed in as <strong>{customer.name || customer.email}</strong>
+          </p>
+          <p className="muted">Role: {customer.role.name}</p>
+
+          <Can
+            subject="profile"
+            action="list"
+            fallback={<p className="muted">Sem permissão de perfil.</p>}
+          >
+            <p>Permissão <code>profile:list</code> concedida.</p>
           </Can>
+
           <button type="button" onClick={() => logout()}>
             Sign out
           </button>
         </>
       ) : (
-        <button
-          type="button"
-          onClick={() =>
-            login({
-              redirectUri: process.env.NEXT_PUBLIC_NSCOPE_REDIRECT_URI,
-            })
-          }
-        >
-          Sign in with Nscope
-        </button>
+        <>
+          <p className="muted">
+            Login hospedado via OAuth. A SDK troca <code>?code=</code> e
+            restaura o token automaticamente.
+          </p>
+          <button
+            type="button"
+            onClick={() =>
+              login({
+                redirectUri: process.env.NEXT_PUBLIC_NSCOPE_REDIRECT_URI,
+              })
+            }
+          >
+            Sign in with Nscope
+          </button>
+        </>
       )}
     </main>
   );

package/templates/next/components/providers.tsx

@@ -1,8 +1,19 @@
 "use client";
 
 import { NscopeProvider } from "@nscope/react";
-import { nscope } from "@/lib/nscope";
+import { nscopeConfig } from "@/lib/nscope";
 
 export function Providers({ children }: { children: React.ReactNode }) {
-  return <NscopeProvider config={nscope}>{children}</NscopeProvider>;
+  return (
+    <NscopeProvider
+      config={nscopeConfig}
+      loadingFallback={
+        <main className="page">
+          <p className="muted">Carregando sessão…</p>
+        </main>
+      }
+    >
+      {children}
+    </NscopeProvider>
+  );
 }

package/templates/next/lib/nscope.ts

@@ -1,10 +1,9 @@
-import { SDK } from "@nscope/sdk";
+import type { SDKConfig } from "@nscope/sdk";
 
-export const nscope = SDK.init({
-  baseUrl: process.env.NEXT_PUBLIC_NSCOPE_BASE_URL!,
-  apiKey: process.env.NEXT_PUBLIC_NSCOPE_API_KEY!,
+export const nscopeConfig: SDKConfig = {
+  apiKey: process.env.NEXT_PUBLIC_NSCOPE_API_KEY,
   auth: {
     autoHandleCallback: true,
     storage: "localStorage",
   },
-});
+};

package/templates/next/package.json

@@ -8,8 +8,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@nscope/react": "^1.0.0",
-    "@nscope/sdk": "^1.3.0",
+    "@nscope/react": "latest",
+    "@nscope/sdk": "latest",
     "next": "^15.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"

package/templates/vite/.env.example

@@ -1,3 +1,8 @@
+# Chave pública do projeto (Configurações → API keys)
 VITE_NSCOPE_API_KEY={{API_KEY}}
-VITE_NSCOPE_BASE_URL={{BASE_URL}}
+
+# URL de retorno após login OAuth (cadastre em Domínios permitidos)
 VITE_NSCOPE_REDIRECT_URI={{REDIRECT_URI}}
+
+# Referência local — a URL da API é definida no build do pacote @nscope/sdk
+# VITE_NSCOPE_BASE_URL={{BASE_URL}}

package/templates/vite/README.md

@@ -13,8 +13,14 @@ pnpm install
 pnpm dev
 ```
 
+## How it works
+
+- `src/nscope.ts` exports `nscopeConfig` (`SDKConfig`) — not a pre-initialized SDK instance.
+- `NscopeProvider` receives `config` and shows `loadingFallback` while `sdk.ready` resolves (OAuth callback + token restore).
+- `useNscope()` exposes `ready`, `authenticated`, `customer`, `permissions`, `login`, `logout`, `can()` and `refresh()`.
+
 ## Next steps
 
-- Customize login redirect in `src/App.tsx`
-- Protect routes with `<GuardedRoute>` from `@nscope/react`
+- Customize login in `src/App.tsx` — `login()` accepts optional `redirectUri`
+- Protect UI with `<Can>` or `<GuardedRoute>` from `@nscope/react`
 - Read the SDK docs in your Nscope panel at `/docs/sdk`

package/templates/vite/package.json

@@ -9,8 +9,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@nscope/react": "^1.0.0",
-    "@nscope/sdk": "^1.3.0",
+    "@nscope/react": "latest",
+    "@nscope/sdk": "latest",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/templates/vite/src/App.tsx

@@ -1,30 +1,48 @@
 import { Can, useNscope } from "@nscope/react";
 
 export default function App() {
-  const { user, isAuthenticated, isLoading, login, logout } = useNscope();
-
-  if (isLoading) {
-    return <main className="page">Loading…</main>;
-  }
+  const { authenticated, customer, login, logout } = useNscope();
 
   return (
     <main className="page">
       <h1>{{PROJECT_NAME}}</h1>
 
-      {isAuthenticated && user ? (
+      {authenticated && customer ? (
         <>
-          <p>Signed in as {user.name ?? user.email}</p>
-          <Can subject="users" action="LIST">
-            <p>You can list users.</p>
+          <p>
+            Signed in as <strong>{customer.name || customer.email}</strong>
+          </p>
+          <p className="muted">Role: {customer.role.name}</p>
+
+          <Can
+            subject="profile"
+            action="list"
+            fallback={<p className="muted">Sem permissão de perfil.</p>}
+          >
+            <p>Permissão <code>profile:list</code> concedida.</p>
           </Can>
+
           <button type="button" onClick={() => logout()}>
             Sign out
           </button>
         </>
       ) : (
-        <button type="button" onClick={() => login({ redirectUri: import.meta.env.VITE_NSCOPE_REDIRECT_URI })}>
-          Sign in with Nscope
-        </button>
+        <>
+          <p className="muted">
+            Login hospedado via OAuth. A SDK troca <code>?code=</code> e
+            restaura o token automaticamente.
+          </p>
+          <button
+            type="button"
+            onClick={() =>
+              login({
+                redirectUri: import.meta.env.VITE_NSCOPE_REDIRECT_URI,
+              })
+            }
+          >
+            Sign in with Nscope
+          </button>
+        </>
       )}
     </main>
   );

package/templates/vite/src/index.css

@@ -19,6 +19,18 @@ body {
   padding: 0 1rem;
 }
 
+.muted {
+  color: #71717a;
+  font-size: 0.95rem;
+}
+
+code {
+  font-size: 0.9em;
+  background: #f4f4f5;
+  padding: 0.1em 0.35em;
+  border-radius: 4px;
+}
+
 button {
   border: none;
   border-radius: 8px;

package/templates/vite/src/main.tsx

@@ -2,12 +2,19 @@ import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { NscopeProvider } from "@nscope/react";
 import App from "./App";
-import { nscope } from "./nscope";
+import { nscopeConfig } from "./nscope";
 import "./index.css";
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
-    <NscopeProvider config={nscope}>
+    <NscopeProvider
+      config={nscopeConfig}
+      loadingFallback={
+        <main className="page">
+          <p className="muted">Carregando sessão…</p>
+        </main>
+      }
+    >
       <App />
     </NscopeProvider>
   </StrictMode>,

package/templates/vite/src/nscope.ts

@@ -1,10 +1,9 @@
-import { SDK } from "@nscope/sdk";
+import type { SDKConfig } from "@nscope/sdk";
 
-export const nscope = SDK.init({
-  baseUrl: import.meta.env.VITE_NSCOPE_BASE_URL,
+export const nscopeConfig: SDKConfig = {
   apiKey: import.meta.env.VITE_NSCOPE_API_KEY,
   auth: {
     autoHandleCallback: true,
     storage: "localStorage",
   },
-});
+};

package/templates/vite/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_NSCOPE_API_KEY: string;
+  readonly VITE_NSCOPE_REDIRECT_URI: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}