@webtwizz/cloud 0.4.0 → 0.5.0

package/AI_GUIDE.md

@@ -2,7 +2,7 @@
 
 Read this before writing sign-ins, database code or file uploads on a site with WebTwizz Cloud. It matches the version installed next to it. Call all of it WebTwizz Cloud (sign-ins, database, files) and never name any company behind it.
 
-Every setting is already in the site's environment (`WEBTWIZZ_AUTH_URL`, `WEBTWIZZ_AUTH_SECRET`, `DATABASE_URL`, `WEBTWIZZ_STORAGE_*`, `WEBTWIZZ_FILES_URL`). Never add, rename or print them.
+Every setting is already in the site's environment (`WEBTWIZZ_AUTH_URL`, `WEBTWIZZ_AUTH_SECRET`, `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `WEBTWIZZ_STORAGE_*`, `WEBTWIZZ_FILES_URL`). Never add, rename or print them.
 
 ## Sign-ins
 
@@ -41,7 +41,15 @@ if (error) setMessage(authMessage(error));
 
 For wording that fits the site, pass overrides: `authMessage(error, { USER_ALREADY_EXISTS: 'You already have a booking account.' })`.
 
-When the owner turns on Confirm email, sign-up returns no session and the 6-digit code is emailed automatically. Show a code step: `authClient.emailOtp.verifyEmail({ email, otp })`, then sign them in, with a "Send a new code" button that calls `authClient.emailOtp.sendVerificationOtp({ email, type: 'email-verification' })`. Never send the first code yourself.
+Confirm email is off unless the owner turns it on in Settings > Cloud > Users, so sign-up signs people straight in and an unconfirmed email never stops a sign-in. When the owner turns on Confirm email, sign-up returns no session and the 6-digit code is emailed automatically. Show a code step: `authClient.emailOtp.verifyEmail({ email, otp })`, then sign them in, with a "Send a new code" button that calls `authClient.emailOtp.sendVerificationOtp({ email, type: 'email-verification' })`. Never send the first code yourself.
+
+Every sign-in form also handles `EMAIL_NOT_VERIFIED`, because the owner can turn Confirm email on at any time: members who joined while it was off then get that error, and a code is emailed to them at once. Keep what they typed, show `authMessage(error)` ("We sent you a code to confirm your email.") and the code field, then `authClient.emailOtp.verifyEmail({ email, otp })` and `authClient.signIn.email({ email, password })` again:
+
+```ts
+const { error } = await authClient.signIn.email({ email, password });
+if (error?.code === 'EMAIL_NOT_VERIFIED') setNeedsCode(true);
+if (error) setMessage(authMessage(error));
+```
 
 5. Protect pages in `src/proxy.ts`, listing only the protected routes in the matcher (a matcher over every path blocks the sign-in page's own scripts):
 
@@ -66,7 +74,35 @@ Never destructure `{ user }` from the top level.
 
 8. Every sign-in page gets a "Forgot password?" link to `/reset-password`, a client page in two steps: their email, then `authClient.forgetPassword.emailOtp({ email })`, which emails a 6-digit code; then the code and a new password, then `authClient.emailOtp.resetPassword({ email, otp, password })`, then send them to sign in. Leave `/reset-password` out of the proxy matcher. The owner can also send a reset code from the Data panel, and it lands on this page.
 
-Sign-ins are email and password only. Sign-in emails (reset codes, confirmations) are sent for the site automatically; never build email sending or add an email service for them. If the user asks for another way to sign in, say WebTwizz Cloud sign-ins are email and password for now and build that.
+9. Admins are accounts whose role is `'admin'`. Admin pages and admin writes check it on the server, the same way as step 6:
+
+```ts
+const { data: session } = await auth.getSession();
+if (session?.user?.role !== 'admin') return Response.json({ error: 'Admins only' }, { status: 403 });
+```
+
+The first admin is the owner's own account on the site: they sign up like any visitor (their WebTwizz account is separate), then make that account an admin under Users in the Data panel, or ask you to do it. A new or removed role reaches their pages within about 10 seconds, and a blocked or deleted account is signed out within the same time.
+
+Sign-ins are email and password, plus Google once the owner turns on Sign in with Google with their own Google app (Settings > Cloud > Users). Sign-in emails (reset codes, confirmations) are sent for the site automatically; never build email sending or add an email service for them. If the user asks for any other way to sign in, say WebTwizz Cloud sign-ins are email and password, and Google, for now.
+
+When Google is on, add a "Continue with Google" button to the sign-in and sign-up forms:
+
+```ts
+const { error } = await authClient.signIn.social({ provider: 'google', callbackURL: '/account' });
+if (error) setMessage(authMessage(error));
+```
+
+The visitor comes back to `callbackURL` signed in, also from inside the builder's preview, where Google opens in a popup. If it fails they come back to the page they started on with `?error=CODE` in the address: show `authMessage({ code })` for it. While Google is off the call returns `PROVIDER_NOT_FOUND`, so only show the button once the owner has turned it on.
+
+Managing users from the site (creating accounts, changing roles, blocking) happens only in server code, a route handler or server action, after checking the signed-in user is an admin as in step 9. It works even when the owner has closed sign-ups:
+
+```ts
+const { data, error } = await auth.admin.createUser({ email, password, name, role: 'user' });
+await auth.admin.setRole({ userId, role: 'admin' });
+await auth.admin.banUser({ userId });
+```
+
+Never manage users from the browser: there `authClient.admin.*`, organizations, magic links and sign-in codes are switched off and return `NOT_FOUND`. Admin pages read `webtwizz.users` on the server, and the owner can also manage users under Users in the Data panel.
 
 Sites built before this package import sign-ins from another package in `src/lib/auth/`. When you work on their sign-ins, move `server.ts`, `client.ts` and the auth route to the files above (same sign-ins, same users) and remove the old package.
 
@@ -96,12 +132,34 @@ import { createDb } from '@webtwizz/cloud/db';
 export const sql = createDb();
 ```
 
-It is the `postgres` package with pooler-safe settings, so queries look like ``await sql`select * from notes where user_id = ${session.user.id}` ``. Schema and data changes go through the `database` tool.
+It is the `postgres` package (version 4) with pooler-safe settings, so queries look like ``await sql`select * from notes where user_id = ${session.user.id}` ``. Pass arrays straight in with a cast, ``where id = any(${ids}::int[])``; there is no `sql.array`. Schema and data changes go through the `database` tool.
+
+`DATABASE_URL` goes through a connection pooler: each query may run on a connection another visitor just used. Never run a session-level `SET` (it leaks to other visitors, and a changed `search_path` breaks their queries) or `LISTEN`/`NOTIFY` (nothing arrives). Put settings inside a transaction with `SET LOCAL`, which ends with it:
+
+```ts
+await sql.begin(async (tx) => {
+  await tx`set local statement_timeout = '5s'`;
+  await tx`update orders set status = 'paid' where id = ${id}`;
+});
+```
+
+Refresh changed data by polling (below) instead of `LISTEN`. Only a long-running script that truly needs one session, never a page or route, connects with `createDb({ url: process.env.DATABASE_URL_UNPOOLED })`.
 
 The database can pause or fill up on the owner's plan. Wrap reads and saves in try/catch and show `MESSAGES.unavailable` on a page or `MESSAGES.saveFailed` on a form (`import { MESSAGES } from '@webtwizz/cloud'`). Visitors never see WebTwizz, plans or limits.
 
 Pages that only show data set `export const revalidate = 60`, and the server action that saves calls `revalidatePath` for them. Pages for a signed-in user stay dynamic.
 
+The database runs while pages read or save data and stops after 5 quiet minutes; its running time comes out of the owner's monthly allowance. So a page that refreshes data on a timer (a feed, a chat, a dashboard) refreshes only while the tab is visible, and again when the visitor comes back:
+
+```ts
+useEffect(() => {
+  const refresh = () => { if (document.visibilityState === 'visible') load(); };
+  const timer = setInterval(refresh, 60_000);
+  document.addEventListener('visibilitychange', refresh);
+  return () => { clearInterval(timer); document.removeEventListener('visibilitychange', refresh); };
+}, []);
+```
+
 ## Files
 
 Two buckets: `public` (anyone can view, for images shown on the site) and `private` (documents, opened through short-lived links). Images you place on pages yourself keep using the usual image tools; this is for what visitors or the site's features upload.
@@ -132,4 +190,4 @@ Show files with `createFiles().publicUrl(key)` in a plain `<img>` or link, or `a
 
 ## Owner tools
 
-The owner manages users under Users in the Data panel (password reset, block, delete with their rows, export), sets who can sign up and the sign-in emails in Settings > Cloud > Users, and downloads everything from Settings > Cloud > Database. Point them there when they ask.
+The owner manages users under Users in the Data panel (make admin, password reset, block, delete with their rows, export), sets who can sign up and the sign-in emails in Settings > Cloud > Users, and downloads everything from Settings > Cloud > Database. Point them there when they ask.

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @webtwizz/cloud
 
+## 0.5.0
+
+### Minor Changes
+
+- 2838972: Sign-ins are now fully WebTwizz's own, with no code from the sign-in service's SDK in the package. Visitors who are signed in today sign in once more after a site moves to this version, because the cookies have new names.
+  
+  - Sign-in forms always get `{ data, error }` back: a wrong password, a taken email, a bad code, a rate limit or a dropped connection no longer throws, so the form stops spinning and `authMessage` shows the right words. A site's own wording for `USER_ALREADY_EXISTS` also applies to the longer code the service sends.
+  - The browser client is Better Auth 1.7.14, matching the hosted service.
+  - Sign in with Google works when the owner has turned it on with their own Google app, read from the site's database. The visitor comes back through the site's own sign-in route, which finishes the sign-in and opens the page the site asked for. Inside the builder's preview, Google opens in a popup. Failures come back to the starting page with `?error=` and plain wording.
+  - Pages that check the session no longer fail with a server error when the session needs its daily renewal, or when the visitor was blocked or deleted: they render, and blocked or deleted visitors read as signed out.
+  - Visitors are no longer signed out 7 days after signing in. Renewed sessions reach the browser wherever the site can set cookies, and the session cookie lasts until the sign-in service ends the session.
+  - The cached session cookie stays small whatever is in a visitor's profile, and never includes the session token.
+  - Blocking, deleting or changing the role of a user takes effect within about 10 seconds instead of 5 minutes. If the sign-in service can't be reached, visitors stay signed in on their last known session for up to an hour.
+  - Cookies are named `__Host-webtwizz-auth.`, so other sites on webtwizz.app can't set or replace them. They carry no Domain, and cookies under any other name are ignored. Inside a frame, such as the builder's preview, they use `SameSite=None; Partitioned`; on plain-http localhost they drop the prefix and `Secure`, which Safari needs.
+  - The site's sign-in route refuses what browsers never need: the service's API reference and keys, admin powers such as signing in as another user or setting passwords, organizations, magic links, link emails, and sign-in codes, which could get around closed sign-ups. Refusals come back as errors `authMessage` words. The site's own server code can still manage users (`auth.admin.createUser`, `setRole` and the rest) after its own admin check; only the API reference, keys and tokens are closed to it.
+  - Every call to the sign-in service carries the visitor's IP address and browser.
+  - "Confirm your email" now reads "We sent you a code to confirm your email.", since the code goes out when an unconfirmed member signs in.
+  - The database client is `postgres` 4, which no longer crashes the server when the database stops in the middle of a transaction. Dates are still sent as before. `sql.array()` is gone: pass arrays directly.
+  - The guide covers the Google button, the code step on sign-in, `SET LOCAL` instead of session-level `SET`, and polling instead of `LISTEN` on the pooled database.
+
+## 0.4.1
+
+### Patch Changes
+
+- 67343d5: Signed-in visitors can sign out, and `authClient` can read their session: since 0.2.0 the sign-in route answered both with a server error inside Next, because it copied a request Next hands over as a Proxy. Visitors who pressed Sign out stayed signed in.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -13,7 +13,7 @@ WebTwizz puts every setting in the site's environment, so each module works with
 | `@webtwizz/cloud` | `authMessage(error)` plain words for sign-in errors, `MESSAGES` for unavailable and failed saves |
 | `@webtwizz/cloud/server` | `createAuth()` with `.handler()`, `.middleware()`, `.getSession()` and the server sign-in methods |
 | `@webtwizz/cloud/client` | `createAuthClient()` for client components |
-| `@webtwizz/cloud/db` | `createDb()`, a `postgres` client with pooler-safe settings |
+| `@webtwizz/cloud/db` | `createDb()`, a `postgres` 4 client with pooler-safe settings |
 | `@webtwizz/cloud/emails` | `handleSignInEmails()` for sites that send their own sign-in emails, `signInEmailCopy()` for the wording |
 | `@webtwizz/cloud/files` | `createFiles()` with `uploadUrl`, `publicUrl`, `privateUrl`, `remove` |
 
@@ -38,7 +38,9 @@ npm run test:integration # real throwaway project, needs NEON_API_KEY
 npm run build
 ```
 
-`test/fixture` is a small Next app that CI builds against the packed tarball.
+`test/fixture` is a small Next app built the way WebTwizz builds sites (the same Next and React versions, `bun install`, `next build --webpack`, the guide's code), which CI builds against the packed tarball.
+
+To try a change in the local WebTwizz preview site without publishing: `npm run preview` builds the package, puts it in the preview container's `node_modules` under a unique dev version, and restarts its dev server (about 10 seconds). `npm run dev` does the same on every save.
 
 ## Releases
 

package/dist/chunk-4PKQUQZD.js

@@ -0,0 +1,6 @@
+// src/frame.ts
+var FRAME_HEADER = "x-webtwizz-frame";
+
+export {
+  FRAME_HEADER
+};

package/dist/{chunk-G54JBUO3.js → chunk-WX3OU7ED.js}

@@ -1,6 +1,7 @@
 // src/errors.ts
 var TRY_LATER = "Sign-in isn't working right now. Please try again in a minute.";
 var TOO_MANY = "Too many tries. Wait a minute and try again.";
+var GOOGLE_FAILED = "Signing in with Google didn't work. Please try again.";
 var AUTH_MESSAGES = {
   INVALID_EMAIL_OR_PASSWORD: "That email or password doesn't match.",
   INVALID_PASSWORD: "That password doesn't match.",
@@ -10,7 +11,7 @@ var AUTH_MESSAGES = {
   USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: "There's already an account with that email.",
   PASSWORD_TOO_SHORT: "Use at least 8 characters for the password.",
   PASSWORD_TOO_LONG: "That password is too long.",
-  EMAIL_NOT_VERIFIED: "Confirm your email first: check your inbox for the code.",
+  EMAIL_NOT_VERIFIED: "We sent you a code to confirm your email.",
   EMAIL_ALREADY_VERIFIED: "Your email is already confirmed. You can sign in.",
   EMAIL_MISMATCH: "That email doesn't match this account.",
   EMAIL_CAN_NOT_BE_UPDATED: "The email on this account can't be changed.",
@@ -31,12 +32,24 @@ var AUTH_MESSAGES = {
   LINKED_ACCOUNT_ALREADY_EXISTS: "That account is already connected.",
   MISSING_FIELD: "Fill in every field and try again.",
   VALIDATION_ERROR: "Check what you entered and try again.",
-  FIELD_NOT_ALLOWED: "Check what you entered and try again."
+  FIELD_NOT_ALLOWED: "Check what you entered and try again.",
+  NOT_FOUND: "That isn't available on this site.",
+  PROVIDER_NOT_FOUND: "This site doesn't offer that way to sign in.",
+  POPUP_BLOCKED: "Allow pop-ups for this site to sign in with Google.",
+  POPUP_CLOSED: "The sign-in window was closed before you finished.",
+  ACCESS_DENIED: "Signing in with Google was cancelled.",
+  SIGNUP_DISABLED: "New accounts can't be made on this site right now.",
+  ACCOUNT_NOT_LINKED: "That email already has an account. Sign in with your password.",
+  SIGN_IN_FAILED: GOOGLE_FAILED,
+  STATE_MISMATCH: GOOGLE_FAILED,
+  INVALID_CODE: GOOGLE_FAILED,
+  PLEASE_RESTART_THE_PROCESS: GOOGLE_FAILED
 };
+var ALIASES = { USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: "USER_ALREADY_EXISTS", PROVIDER_NOT_SUPPORTED: "PROVIDER_NOT_FOUND" };
 function authMessage(error, overrides = {}) {
   if (error?.status === 429) return overrides.TOO_MANY_ATTEMPTS ?? TOO_MANY;
-  const code = error?.code;
-  return code && (overrides[code] ?? AUTH_MESSAGES[code]) || TRY_LATER;
+  const code = typeof error?.code === "string" ? error.code.toUpperCase() : void 0;
+  return code && (overrides[code] ?? overrides[ALIASES[code]] ?? AUTH_MESSAGES[code] ?? AUTH_MESSAGES[ALIASES[code]]) || TRY_LATER;
 }
 var MESSAGES = {
   unavailable: "This isn't available right now. Please try again later.",

package/dist/client.d.ts

@@ -1,6 +1,15 @@
-import { createAuthClient as createAuthClient$1 } from '@neondatabase/auth/next';
+import { adminClient, emailOTPClient } from 'better-auth/client/plugins';
+import { createAuthClient as createAuthClient$1 } from 'better-auth/react';
 
-type AuthClient = ReturnType<typeof createAuthClient$1>;
-declare function createAuthClient(): AuthClient;
+type AuthClientPlugins = Array<ReturnType<typeof adminClient<{}>> | ReturnType<typeof emailOTPClient>>;
+type AuthClient = ReturnType<typeof createAuthClient$1<{
+    plugins: AuthClientPlugins;
+}>>;
+type AuthClientOptions = {
+    /** The site's auth route; only needed outside the browser. */
+    baseURL?: string;
+};
+/** Every call returns { data, error } and never throws, so a form can always show the error and stop spinning. */
+declare function createAuthClient(options?: AuthClientOptions): AuthClient;
 
-export { type AuthClient, createAuthClient };
+export { type AuthClient, type AuthClientOptions, type AuthClientPlugins, createAuthClient };