naystack 1.2.13 → 1.2.15

package/README.md

@@ -19,13 +19,15 @@ yarn add naystack
 
 Naystack provides the following modules, each accessible via its own import path:
 
-| Module      | Import Path        | Description                                     |
-| ----------- | ------------------ | ----------------------------------------------- |
-| **Auth**    | `naystack/auth`    | Email, Google, and Instagram authentication     |
-| **GraphQL** | `naystack/graphql` | GraphQL server initialization with type-graphql |
-| **Client**  | `naystack/client`  | Client-side hooks and utilities                 |
-| **File**    | `naystack/file`    | File upload to AWS S3                           |
-| **Socials** | `naystack/socials` | Instagram and Threads API integration           |
+| Module      | Import Path                | Description                                                        |
+| ----------- | -------------------------- | ------------------------------------------------------------------ |
+| **Auth**    | `naystack/auth`           | Email, Google, and Instagram authentication (server-side routes)  |
+| **Auth UI** | `naystack/auth/email/client` | Client-side React hooks for login / signup / logout flows     |
+| **GraphQL** | `naystack/graphql`        | GraphQL server initialization with type-graphql                   |
+| **GQL App** | `naystack/graphql/client` / `naystack/graphql/server` | Apollo Client helpers for Next.js App Router (client + server) |
+| **Client**  | `naystack/client`         | Generic client-side hooks and utilities                            |
+| **File**    | `naystack/file`           | File upload to AWS S3                                              |
+| **Socials** | `naystack/socials`        | Instagram and Threads API integration                              |
 
 ---
 
@@ -39,11 +41,21 @@ import {
 } from "naystack/auth";
 ```
 
+### High-level Auth Flow in a Next.js App Router project
+
+From a real-world setup (like `veas-web`), the pieces look like this:
+
+- **Server-side auth routes** – created with `getEmailAuthRoutes` (and optionally Google / Instagram)
+- **Server-side GraphQL context** – uses `getUserIdFromRequest` from the email auth routes
+- **Client-side auth hooks** – created with `getEmailAuthUtils` and used in login/signup/logout forms
+
+The sections below show each part in more detail.
+
 ### Email Authentication
 
 Setup email-based authentication with JWT tokens and optional Turnstile captcha verification.
 
-**Basic Example:**
+**Next.js App Router Example (server routes):**
 
 ```typescript
 const emailAuth = getEmailAuthRoutes({
@@ -61,6 +73,101 @@ const emailAuth = getEmailAuthRoutes({
 export const { GET, POST, PUT, DELETE, getUserIdFromRequest } = emailAuth;
 ```
 
+**Client-side hooks (login, signup, logout) – as used in `veas-web`:**
+
+```typescript
+// app/(auth)/utils.ts
+import { getEmailAuthUtils } from "naystack/auth/email/client";
+
+// The argument is the URL where your email auth API lives
+export const { useLogin, useLogout, useSignUp } =
+  getEmailAuthUtils("/api/email");
+```
+
+```typescript
+// app/(auth)/login/components/form.tsx
+"use client";
+import React, { useState } from "react";
+import { useLogin } from "@/app/(auth)/utils";
+import { useRouter } from "next/navigation";
+
+export default function LoginForm() {
+  const login = useLogin();
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+
+  return (
+    <form
+      onSubmit={async (e) => {
+        e.preventDefault();
+        const ok = await login({ email, password });
+        if (ok) router.push("/dashboard");
+      }}
+    >
+      {/* inputs + submit */}
+    </form>
+  );
+}
+```
+
+```typescript
+// app/(auth)/signup/components/form.tsx
+"use client";
+import React, { useState } from "react";
+import { useSignUp } from "@/app/(auth)/utils";
+import { useRouter } from "next/navigation";
+
+export default function SignupForm() {
+  const signUp = useSignUp();
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+
+  return (
+    <form
+      onSubmit={async (e) => {
+        e.preventDefault();
+        const ok = await signUp({ email, password });
+        if (ok) router.push("/onboard");
+      }}
+    >
+      {/* inputs + submit */}
+    </form>
+  );
+}
+```
+
+```typescript
+// app/dashboard/components/logout-button.tsx
+"use client";
+import React, { useState } from "react";
+import { useLogout } from "@/app/(auth)/utils";
+import { useRouter } from "next/navigation";
+
+export default function LogoutButton() {
+  const logout = useLogout();
+  const [loading, setLoading] = useState(false);
+  const router = useRouter();
+
+  const handleLogout = async () => {
+    setLoading(true);
+    try {
+      await logout();
+      router.push("/login");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <button onClick={handleLogout} disabled={loading}>
+      {loading ? "Logging out..." : "Logout"}
+    </button>
+  );
+}
+```
+
 **Real-World Example with Drizzle ORM:**
 
 ```typescript
@@ -302,7 +409,7 @@ import {
 import type { Context, AuthorizedContext } from "naystack/graphql";
 ```
 
-### Initialize GraphQL Server
+### Initialize GraphQL Server (Next.js App Router)
 
 **Basic Example:**
 
@@ -357,6 +464,17 @@ export const { GET, POST } = await initGraphQLServer({
 });
 ```
 
+### Real-world pattern from a full Next.js app (like `veas-web`)
+
+In a typical app you will:
+
+- Define **GraphQL resolvers** using `QueryLibrary` / `FieldLibrary`
+- Initialize the GraphQL **API route** with `initGraphQLServer`
+- Use **server-side helper** `getGraphQLQuery` to call GraphQL from RSC / server actions
+- Use **client-side helper** `getApolloWrapper` and `useAuthMutation` for client components
+
+The next sections show how these pieces fit together.
+
 #### Options
 
 | Option        | Type                                 | Required | Description                      |
@@ -483,6 +601,139 @@ const fields = {
 const UserFieldResolver = FieldLibrary(User, fields);
 ```
 
+**How this looks in a real app (`veas-web`-style):**
+
+```typescript
+// app/api/(graphql)/User/db.ts
+import { pgTable, serial, text, timestamp, real } from "drizzle-orm/pg-core";
+
+export const UserTable = pgTable("users", {
+  id: serial("id").primaryKey(),
+  email: text("email").notNull(),
+  password: text("password").notNull(),
+  name: text("name"),
+  dateOfBirth: timestamp("date_of_birth"),
+  placeOfBirthLat: real("place_of_birth_lat"),
+  placeOfBirthLong: real("place_of_birth_long"),
+  timezone: real("timezone"),
+});
+
+export type UserDB = typeof UserTable.$inferSelect;
+```
+
+```typescript
+// app/api/(graphql)/User/types.ts
+import { Field, ObjectType } from "type-graphql";
+
+@ObjectType("User")
+export class User {
+  @Field()
+  id: number;
+
+  @Field()
+  email: string;
+
+  @Field(() => String, { nullable: true })
+  name: string | null;
+
+  @Field(() => Date, { nullable: true })
+  dateOfBirth: Date | null;
+
+  @Field(() => Number, { nullable: true })
+  placeOfBirthLat: number | null;
+
+  @Field(() => Number, { nullable: true })
+  placeOfBirthLong: number | null;
+
+  @Field(() => Number, { nullable: true })
+  timezone: number | null;
+
+  @Field()
+  isOnboarded: boolean;
+}
+```
+
+```typescript
+// app/api/(graphql)/User/resolvers/is-onboarded.ts
+import { field } from "naystack/graphql";
+import type { UserDB } from "../db";
+
+export default field(
+  async (user: UserDB) => {
+    return (
+      !!user.name &&
+      !!user.dateOfBirth &&
+      user.placeOfBirthLat !== null &&
+      user.placeOfBirthLong !== null &&
+      user.timezone !== null
+    );
+  },
+  { output: Boolean },
+);
+```
+
+```typescript
+// app/api/(graphql)/User/resolvers/get-current-user.ts
+import { query } from "naystack/graphql";
+import { db } from "@/app/api/lib/db";
+import { UserTable } from "../db";
+import { eq } from "drizzle-orm";
+import { User } from "../types";
+
+export default query(
+  async (ctx: { userId: number | null }) => {
+    if (!ctx.userId) return null;
+    const [user] = await db
+      .select()
+      .from(UserTable)
+      .where(eq(UserTable.id, ctx.userId));
+    return user || null;
+  },
+  {
+    output: User,
+  },
+);
+```
+
+```typescript
+// app/api/(graphql)/User/graphql.ts
+import { QueryLibrary, FieldLibrary } from "naystack/graphql";
+import getCurrentUser from "./resolvers/get-current-user";
+import onboardUser from "./resolvers/onboard-user";
+import isOnboarded from "./resolvers/is-onboarded";
+import type { UserDB } from "./db";
+import { User } from "./types";
+
+export const UserResolvers = QueryLibrary({
+  getCurrentUser,
+  onboardUser,
+});
+
+export const UserFieldResolvers = FieldLibrary<UserDB>(User, {
+  isOnboarded,
+});
+```
+
+```typescript
+// app/api/(graphql)/route.ts
+import { initGraphQLServer } from "naystack/graphql";
+import { UserResolvers, UserFieldResolvers } from "./User/graphql";
+import { getUserIdFromRequest } from "@/app/api/(auth)/email";
+
+export const { GET, POST } = await initGraphQLServer({
+  resolvers: [UserResolvers, UserFieldResolvers],
+  context: async (req) => {
+    const res = getUserIdFromRequest(req);
+    if (!res) return { userId: null };
+    return {
+      userId: res.accessUserId ?? res.refreshUserID ?? null,
+    };
+  },
+});
+```
+
+This gives you a full GraphQL API route that uses Naystack’s auth, Drizzle models, and functional resolvers.
+
 **Real-World Example:**
 
 ```typescript

package/dist/graphql/index.cjs.js

@@ -655,6 +655,9 @@ function QueryLibrary(queries) {
         descriptor
       );
     }
+    if (def.authorized) {
+      (0, import_type_graphql2.Authorized)()(GeneratedResolver, key);
+    }
     (0, import_type_graphql2.Ctx)()(GeneratedResolver.prototype, key, 0);
     if (def.input) {
       (0, import_type_graphql2.Arg)("input", () => def.input || String, def.inputOptions)(

package/dist/graphql/index.esm.js

@@ -651,6 +651,9 @@ function QueryLibrary(queries) {
         descriptor
       );
     }
+    if (def.authorized) {
+      Authorized()(GeneratedResolver, key);
+    }
     Ctx()(GeneratedResolver.prototype, key, 0);
     if (def.input) {
       Arg("input", () => def.input || String, def.inputOptions)(

package/dist/graphql/server.cjs.js

@@ -25,6 +25,7 @@ __export(server_exports, {
 });
 module.exports = __toCommonJS(server_exports);
 var import_client = require("@apollo/client");
+var import_client_integration_nextjs = require("@apollo/client-integration-nextjs");
 var import_headers = require("next/headers");
 var import_react = require("react");
 function Injector({
@@ -43,14 +44,16 @@ async function InjectorSuspensed({
   return /* @__PURE__ */ React.createElement(Component, { loading: false, ...props || {}, data });
 }
 var getGraphQLQuery = ({ uri }) => {
-  const client = new import_client.ApolloClient({
-    cache: new import_client.InMemoryCache(),
-    link: new import_client.HttpLink({
-      uri
-    })
+  const { query } = (0, import_client_integration_nextjs.registerApolloClient)(() => {
+    return new import_client.ApolloClient({
+      cache: new import_client.InMemoryCache(),
+      link: new import_client.HttpLink({
+        uri
+      })
+    });
   });
   return async (_query, options) => {
-    const res = await client.query({
+    const res = await query({
       query: _query,
       variables: options?.variables,
       context: {

package/dist/graphql/server.esm.js

@@ -4,6 +4,7 @@ import {
   HttpLink,
   InMemoryCache
 } from "@apollo/client";
+import { registerApolloClient } from "@apollo/client-integration-nextjs";
 import { cookies } from "next/headers";
 import { Suspense } from "react";
 function Injector({
@@ -22,14 +23,16 @@ async function InjectorSuspensed({
   return /* @__PURE__ */ React.createElement(Component, { loading: false, ...props || {}, data });
 }
 var getGraphQLQuery = ({ uri }) => {
-  const client = new ApolloClient({
-    cache: new InMemoryCache(),
-    link: new HttpLink({
-      uri
-    })
+  const { query } = registerApolloClient(() => {
+    return new ApolloClient({
+      cache: new InMemoryCache(),
+      link: new HttpLink({
+        uri
+      })
+    });
   });
   return async (_query, options) => {
-    const res = await client.query({
+    const res = await query({
       query: _query,
       variables: options?.variables,
       context: {

package/dist/graphql/utils.cjs.js

@@ -73,6 +73,9 @@ function QueryLibrary(queries) {
         descriptor
       );
     }
+    if (def.authorized) {
+      (0, import_type_graphql.Authorized)()(GeneratedResolver, key);
+    }
     (0, import_type_graphql.Ctx)()(GeneratedResolver.prototype, key, 0);
     if (def.input) {
       (0, import_type_graphql.Arg)("input", () => def.input || String, def.inputOptions)(

package/dist/graphql/utils.d.mts

@@ -1,6 +1,6 @@
 import { GraphQLScalarType } from 'graphql';
 import { ClassType, Query, Arg } from 'type-graphql';
-import { Context } from './types.mjs';
+import { AuthorizedContext, Context } from './types.mjs';
 
 type ReturnOptions = Parameters<typeof Query>[1];
 type ArgsOptions = Parameters<typeof Arg>[2];
@@ -9,26 +9,26 @@ type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
 type OtherTypes<T> = GraphQLScalarType<T, T> | [GraphQLScalarType<T, T>] | NumberConstructor | [NumberConstructor] | StringConstructor | [StringConstructor] | BooleanConstructor | [BooleanConstructor];
-interface BaseDefinition<T extends Values, U extends Values> {
+interface BaseDefinition<T extends Values, U extends Values, IsAuth extends boolean> {
     output: T extends object ? ClassType<DeepPartial<T>> | [ClassType<DeepPartial<T>>] : OtherTypes<T>;
     outputOptions?: ReturnOptions;
     input?: U extends object ? ClassType<U> | [ClassType<U>] : OtherTypes<U>;
     inputOptions?: ArgsOptions;
-    authorized?: boolean;
+    authorized?: IsAuth;
 }
-interface QueryDefinition<T extends Values, U extends Values> extends BaseDefinition<T, U> {
-    fn: (ctx: Context, data: U) => Promise<T | T[]> | T | T[];
+interface QueryDefinition<T extends Values, U extends Values, IsAuth extends boolean> extends BaseDefinition<T, U, IsAuth> {
+    fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: U) => Promise<T | T[]> | T | T[];
     mutation?: boolean;
 }
-interface FieldResolverDefinition<T extends Values, U extends Values, Root> extends BaseDefinition<T, U> {
-    fn: (root: Root, ctx: Context, data: U) => Promise<T | T[]> | T | T[];
+interface FieldResolverDefinition<T extends Values, U extends Values, IsAuth extends boolean, Root> extends BaseDefinition<T, U, IsAuth> {
+    fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: U) => Promise<T | T[]> | T | T[];
 }
-declare function query<T extends Values, U extends Values>(fn: QueryDefinition<T, U>["fn"], options: Omit<QueryDefinition<T, U>, "fn">): QueryDefinition<T, U>;
-declare function field<T extends Values, U extends Values, Root>(fn: FieldResolverDefinition<T, U, Root>["fn"], options: Omit<FieldResolverDefinition<T, U, Root>, "fn">): FieldResolverDefinition<T, U, Root>;
-declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any>>>(queries: T): {
+declare function query<T extends Values, U extends Values, IsAuth extends boolean>(fn: QueryDefinition<T, U, IsAuth>["fn"], options: Omit<QueryDefinition<T, U, IsAuth>, "fn">): QueryDefinition<T, U, IsAuth>;
+declare function field<T extends Values, U extends Values, IsAuth extends boolean, Root>(fn: FieldResolverDefinition<T, U, IsAuth, Root>["fn"], options: Omit<FieldResolverDefinition<T, U, IsAuth, Root>, "fn">): FieldResolverDefinition<T, U, IsAuth, Root>;
+declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any, any>>>(queries: T): {
     new (): {};
 };
-declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, X>> = Record<string, FieldResolverDefinition<any, any, X>>>(type: ClassType, queries: T): {
+declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, any, X>> = Record<string, FieldResolverDefinition<any, any, any, X>>>(type: ClassType, queries: T): {
     new (): {};
 };
 

package/dist/graphql/utils.d.ts

@@ -1,6 +1,6 @@
 import { GraphQLScalarType } from 'graphql';
 import { ClassType, Query, Arg } from 'type-graphql';
-import { Context } from './types.js';
+import { AuthorizedContext, Context } from './types.js';
 
 type ReturnOptions = Parameters<typeof Query>[1];
 type ArgsOptions = Parameters<typeof Arg>[2];
@@ -9,26 +9,26 @@ type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
 type OtherTypes<T> = GraphQLScalarType<T, T> | [GraphQLScalarType<T, T>] | NumberConstructor | [NumberConstructor] | StringConstructor | [StringConstructor] | BooleanConstructor | [BooleanConstructor];
-interface BaseDefinition<T extends Values, U extends Values> {
+interface BaseDefinition<T extends Values, U extends Values, IsAuth extends boolean> {
     output: T extends object ? ClassType<DeepPartial<T>> | [ClassType<DeepPartial<T>>] : OtherTypes<T>;
     outputOptions?: ReturnOptions;
     input?: U extends object ? ClassType<U> | [ClassType<U>] : OtherTypes<U>;
     inputOptions?: ArgsOptions;
-    authorized?: boolean;
+    authorized?: IsAuth;
 }
-interface QueryDefinition<T extends Values, U extends Values> extends BaseDefinition<T, U> {
-    fn: (ctx: Context, data: U) => Promise<T | T[]> | T | T[];
+interface QueryDefinition<T extends Values, U extends Values, IsAuth extends boolean> extends BaseDefinition<T, U, IsAuth> {
+    fn: (ctx: IsAuth extends true ? AuthorizedContext : Context, data: U) => Promise<T | T[]> | T | T[];
     mutation?: boolean;
 }
-interface FieldResolverDefinition<T extends Values, U extends Values, Root> extends BaseDefinition<T, U> {
-    fn: (root: Root, ctx: Context, data: U) => Promise<T | T[]> | T | T[];
+interface FieldResolverDefinition<T extends Values, U extends Values, IsAuth extends boolean, Root> extends BaseDefinition<T, U, IsAuth> {
+    fn: (root: Root, ctx: IsAuth extends true ? AuthorizedContext : Context, data: U) => Promise<T | T[]> | T | T[];
 }
-declare function query<T extends Values, U extends Values>(fn: QueryDefinition<T, U>["fn"], options: Omit<QueryDefinition<T, U>, "fn">): QueryDefinition<T, U>;
-declare function field<T extends Values, U extends Values, Root>(fn: FieldResolverDefinition<T, U, Root>["fn"], options: Omit<FieldResolverDefinition<T, U, Root>, "fn">): FieldResolverDefinition<T, U, Root>;
-declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any>>>(queries: T): {
+declare function query<T extends Values, U extends Values, IsAuth extends boolean>(fn: QueryDefinition<T, U, IsAuth>["fn"], options: Omit<QueryDefinition<T, U, IsAuth>, "fn">): QueryDefinition<T, U, IsAuth>;
+declare function field<T extends Values, U extends Values, IsAuth extends boolean, Root>(fn: FieldResolverDefinition<T, U, IsAuth, Root>["fn"], options: Omit<FieldResolverDefinition<T, U, IsAuth, Root>, "fn">): FieldResolverDefinition<T, U, IsAuth, Root>;
+declare function QueryLibrary<T extends Record<string, QueryDefinition<any, any, any>>>(queries: T): {
     new (): {};
 };
-declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, X>> = Record<string, FieldResolverDefinition<any, any, X>>>(type: ClassType, queries: T): {
+declare function FieldLibrary<X extends object, T extends Record<string, FieldResolverDefinition<any, any, any, X>> = Record<string, FieldResolverDefinition<any, any, any, X>>>(type: ClassType, queries: T): {
     new (): {};
 };
 

package/dist/graphql/utils.esm.js

@@ -58,6 +58,9 @@ function QueryLibrary(queries) {
         descriptor
       );
     }
+    if (def.authorized) {
+      Authorized()(GeneratedResolver, key);
+    }
     Ctx()(GeneratedResolver.prototype, key, 0);
     if (def.input) {
       Arg("input", () => def.input || String, def.inputOptions)(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naystack",
-  "version": "1.2.13",
+  "version": "1.2.15",
   "description": "A stack built with Next + GraphQL + S3 + Auth",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",