@starci/hfs 4.2.13 → 4.2.14

package/templates/be/table/api/get.mapper.ts.tpl

@@ -0,0 +1,9 @@
+import type { Get{{Singular}}Request, Get{{Singular}}Result } from "../../application/get-{{singular}}.contracts"
+import type { Get{{Singular}}Input } from "./dto/get-{{singular}}.input"
+import type { Get{{Singular}}Type } from "./dto/get-{{singular}}.type"
+
+/** Maps the GraphQL input to the query request. */
+export const toGet{{Singular}}Request = (input: Get{{Singular}}Input): Get{{Singular}}Request => ({ id: input.id })
+
+/** Maps the result to the GraphQL type. */
+export const toGet{{Singular}}Type = (result: Get{{Singular}}Result): Get{{Singular}}Type => ({ id: result.id })

package/templates/be/table/api/get.query.ts.tpl

@@ -0,0 +1,10 @@
+import { Query } from "@nestjs/cqrs"
+import type { ExecuteParams } from "@modules/platform/cqrs"
+import type { Get{{Singular}}Request, Get{{Singular}}Result } from "./get-{{singular}}.contracts"
+
+/** Asks for one {{singular}} row the authenticated caller owns. */
+export class Get{{Singular}}Query extends Query<Get{{Singular}}Result> {
+    constructor(readonly params: ExecuteParams<Get{{Singular}}Request>) {
+        super()
+    }
+}

package/templates/be/table/api/get.resolver.ts.tpl

@@ -0,0 +1,27 @@
+import { Args, Query, Resolver } from "@nestjs/graphql"
+import type { QueryBus } from "@nestjs/cqrs"
+import { CurrentPrincipal } from "@modules/domain/identity"
+import { InjectQueryBus } from "@modules/platform/cqrs"
+import type { Principal } from "@modules/platform/cqrs"
+import { Get{{Singular}}Query } from "../../application/get-{{singular}}.query"
+import { Get{{Singular}}Input } from "./dto/get-{{singular}}.input"
+import { Get{{Singular}}Type } from "./dto/get-{{singular}}.type"
+import { toGet{{Singular}}Request, toGet{{Singular}}Type } from "./get-{{singular}}.mapper"
+
+@Resolver()
+/** GraphQL door of get-{{singular}}: one {{singular}} row of the caller. */
+export class Get{{Singular}}Resolver {
+    constructor(@InjectQueryBus() private readonly queryBus: QueryBus) {}
+
+    /** Answers one {{singular}} row the caller owns; another owner's row is not found. */
+    @Query(() => Get{{Singular}}Type, { name: "{{singularCamel}}" })
+    async {{singularCamel}}(
+        @CurrentPrincipal() principal: Principal,
+        @Args("input") input: Get{{Singular}}Input,
+    ): Promise<Get{{Singular}}Type> {
+        const result = await this.queryBus.execute(
+            new Get{{Singular}}Query({ request: toGet{{Singular}}Request(input), principal }),
+        )
+        return toGet{{Singular}}Type(result)
+    }
+}

package/templates/be/table/api/get.type.ts.tpl

@@ -0,0 +1,9 @@
+import { Field, ID, ObjectType } from "@nestjs/graphql"
+
+@ObjectType()
+/** The get-{{singular}} answer. */
+export class Get{{Singular}}Type {
+    /** The id of the {{singular}} row. */
+    @Field(() => ID)
+    id!: string
+}

package/templates/be/table/api/graphql.module.ts.tpl

@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common"
+import { {{Name}}ApiModule } from "../../{{name}}.module"
+import { Create{{Singular}}Resolver } from "./create-{{singular}}.resolver"
+import { Get{{Singular}}Resolver } from "./get-{{singular}}.resolver"
+
+@Module({ imports: [{{Name}}ApiModule], providers: [Get{{Singular}}Resolver, Create{{Singular}}Resolver] })
+/** The GraphQL transport of the {{name}} feature. */
+export class {{Name}}GraphqlModule {}

package/templates/be/table/error.api.ts.tpl

@@ -0,0 +1,19 @@
+import { DomainError } from "@modules/platform/errors"
+import type { ErrorKind } from "@modules/platform/errors"
+
+/** Codes of the {{name}} capability. */
+export enum {{Name}}ErrorCode {
+    /** No row owned by the authenticated principal has the requested id. */
+    NotFound = "{{upper}}_NOT_FOUND",
+    /** The database accepted the insert of a new row but answered no id. */
+    NotCreated = "{{upper}}_NOT_CREATED",
+}
+
+/** How each {{name}} code travels. */
+export const {{upper}}_ERROR_KINDS: Record<{{Name}}ErrorCode, ErrorKind> = {
+    [{{Name}}ErrorCode.NotFound]: "not-found",
+    [{{Name}}ErrorCode.NotCreated]: "unavailable",
+}
+
+/** The one error class of the {{name}} capability. */
+export class {{Name}}Error extends DomainError<{{Name}}ErrorCode> {}

package/templates/be/table/migration.sql.tpl

@@ -14,38 +14,30 @@ before update on public.{{tableSql}}
 for each row
 execute function private.set_updated_at();
 
-create policy "{{table}}_authenticated_select"
+create policy "{{table}}_app_be_select"
 on public.{{tableSql}}
 for select
-to authenticated
-using (owner_id = (select auth.uid()));
+to app_be
+using (owner_id is not null);
 
-create policy "{{table}}_authenticated_insert"
+create policy "{{table}}_app_be_insert"
 on public.{{tableSql}}
 for insert
-to authenticated
-with check (owner_id = (select auth.uid()));
+to app_be
+with check (owner_id is not null);
 
-create policy "{{table}}_authenticated_update"
+create policy "{{table}}_app_be_update"
 on public.{{tableSql}}
 for update
-to authenticated
-using (owner_id = (select auth.uid()))
-with check (owner_id = (select auth.uid()));
+to app_be
+using (owner_id is not null)
+with check (owner_id is not null);
 
-create policy "{{table}}_authenticated_delete"
+create policy "{{table}}_app_be_delete"
 on public.{{tableSql}}
 for delete
-to authenticated
-using (owner_id = (select auth.uid()));
-
-create policy "{{table}}_app_be_select"
-on public.{{tableSql}}
-for select
 to app_be
 using (owner_id is not null);
 
-revoke all on table public.{{tableSql}} from public, anon;
-grant select, insert, delete on table public.{{tableSql}} to authenticated;
-grant update (updated_at) on table public.{{tableSql}} to authenticated;
-grant select on table public.{{tableSql}} to app_be;
+revoke all on table public.{{tableSql}} from public, anon, authenticated;
+grant select, insert, update, delete on table public.{{tableSql}} to app_be;

package/templates/be/table/service.api.ts.tpl

@@ -0,0 +1,30 @@
+import { Injectable } from "@nestjs/common"
+import type { EntityManager } from "typeorm"
+import { InjectPrimaryEntityManager, requireOwnedRow } from "@modules/platform/database"
+import { {{Name}}Error, {{Name}}ErrorCode } from "./errors/{{name}}.error"
+import type { {{Name}}Row } from "./persistence/{{name}}.rows"
+import { FIND_{{upper}}, INSERT_{{upper}} } from "./persistence/{{name}}.sql"
+
+interface {{Name}}Result {
+    readonly id: string
+}
+
+@Injectable()
+/** The {{name}} rows reached only through the shared primary EntityManager. */
+export class {{Name}}Service {
+    constructor(@InjectPrimaryEntityManager() private readonly entityManager: EntityManager) {}
+
+    /** Answers one row owned by the authenticated principal; absent and denied rows share one typed not-found result. */
+    {{nameCamel}}(principalId: string, id: string): Promise<{{Name}}Result> {
+        return requireOwnedRow<Pick<{{Name}}Row, "id">>(this.entityManager, FIND_{{upper}}, id, principalId, () => {
+            throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotFound, params: { id } })
+        })
+    }
+
+    /** Creates one row owned by the authenticated principal and answers its id. */
+    async create{{Singular}}(principalId: string): Promise<{{Name}}Result> {
+        const [row] = await this.entityManager.query<Array<Pick<{{Name}}Row, "id">>>(INSERT_{{upper}}, [principalId])
+        if (row === undefined) throw new {{Name}}Error({ code: {{Name}}ErrorCode.NotCreated })
+        return { id: row.id }
+    }
+}

package/templates/be/table/sql.api.ts.tpl

@@ -0,0 +1,7 @@
+import { sql } from "@modules/platform/database"
+
+/** Reads one public.{{table}} row by id and owner through a branded SQL statement. */
+export const FIND_{{upper}} = sql`SELECT id FROM public.{{tableSql}} WHERE id = $1 AND owner_id = $2 LIMIT 1`
+
+/** Inserts one public.{{table}} row owned by the principal and returns its id. */
+export const INSERT_{{upper}} = sql`INSERT INTO public.{{tableSql}} (owner_id) VALUES ($1) RETURNING id`

package/templates/fe/{skeleton-lite/apps/web → skeleton/apps/__app__}/src/components/blocks/SignInForm/index.tsx

@@ -1,35 +1,33 @@
 "use client"
 
 import { useTranslations } from "next-intl"
-import { useState, useTransition } from "react"
-import { writeSignIn } from "@/modules/db/auth/write-sign-in"
-import { navigation } from "@/modules/i18n"
+import { useSession, useSignIn } from "@/hooks/auth"
+import type { SignInFailure } from "@/hooks/auth"
 import { SignInFormBase } from "./component"
 
-type SignInFailure = "refused" | "not-found" | "invalid" | "unavailable"
-
 /** The state the form shows: working while a request runs, failed after a refusal, else ready. */
 const stateOf = (pending: boolean, failure: SignInFailure | undefined): "working" | "ready" | "failed" => {
     if (pending) return "working"
     return failure === undefined ? "ready" : "failed"
 }
 
-/** The interactive sign-in form wired to the schema-checked Server Action. */
+/** The fields of the submitted form, or undefined when one is missing. */
+const credentialsOf = (input: FormData): { readonly email: string; readonly password: string } | undefined => {
+    const email = input.get("email")
+    const password = input.get("password")
+    return typeof email === "string" && typeof password === "string" ? { email, password } : undefined
+}
+
+/** The sign-in form of a signed-out reader; the session effect moves the reader to signed in on success. */
 export const SignInForm = () => {
-    const router = navigation.useRouter()
+    const session = useSession()
     const t = useTranslations("app.signIn")
-    const [failure, setFailure] = useState<SignInFailure>()
-    const [pending, startTransition] = useTransition()
+    const { failure, pending, signIn, reject } = useSignIn()
+    if (session.status !== "signed-out") return null
     const submit = (input: FormData) => {
-        startTransition(async () => {
-            const outcome = await writeSignIn(input)
-            if (outcome.kind === "ok") {
-                setFailure(undefined)
-                router.refresh()
-                return
-            }
-            setFailure(outcome.kind)
-        })
+        const credentials = credentialsOf(input)
+        if (credentials === undefined) reject()
+        else signIn(credentials.email, credentials.password)
     }
     return (
         <SignInFormBase

package/templates/fe/{skeleton-lite/apps/web → skeleton/apps/__app__}/src/components/blocks/SignOutButton/component.tsx

@@ -2,16 +2,20 @@ import { Button, Text } from "@starci/grammar/common"
 
 /** Copy, state and action supplied by the connected sign-out block. */
 export interface SignOutButtonBaseProps {
-    readonly props: { readonly label: string; readonly pending: boolean; readonly failure?: string }
+    readonly props: {
+        readonly principal: string
+        readonly label: string
+        readonly pending: boolean
+    }
     readonly on: { readonly press: () => void }
 }
 
-/** Draws the sign-out control without reading navigation, copy or database state. */
+/** Draws the signed-in reader and the sign-out control without reading navigation, copy or session state. */
 export const SignOutButtonBase = (props: SignOutButtonBaseProps) => (
     <>
+        <Text>{props.props.principal}</Text>
         <Button variant="secondary" isPending={props.props.pending} onPress={props.on.press}>
             {props.props.label}
         </Button>
-        {props.props.failure === undefined ? null : <Text live="assertive">{props.props.failure}</Text>}
     </>
 )

package/templates/fe/skeleton/apps/__app__/src/components/blocks/SignOutButton/index.tsx

@@ -0,0 +1,23 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { useSession, useSignOut } from "@/hooks/auth"
+import { SignOutButtonBase } from "./component"
+
+/** The signed-in reader and the control that ends the browser session. */
+export const SignOutButton = () => {
+    const session = useSession()
+    const t = useTranslations("app.signOut")
+    const { pending, signOut } = useSignOut()
+    if (session.status !== "signed-in") return null
+    return (
+        <SignOutButtonBase
+            props={{
+                principal: session.session?.email ?? t("signedIn"),
+                label: pending ? t("working") : t("submit"),
+                pending,
+            }}
+            on={{ press: signOut }}
+        />
+    )
+}

package/templates/fe/skeleton/apps/__app__/src/components/providers/AppProviders/index.tsx

@@ -0,0 +1,49 @@
+"use client"
+
+import { ToastProvider } from "@heroui/react"
+import { ThemeProvider } from "next-themes"
+import type { ReactNode } from "react"
+import { SWRConfig } from "swr"
+import { useAuthSessionEffect } from "@/hooks/effects"
+import { SwrSideEffects } from "@/hooks/swr"
+import { ReduxProvider } from "@/redux"
+
+/** What the app providers wrap: the routed tree. */
+type AppProvidersProps = { readonly children: ReactNode }
+
+/**
+ * The SWR defaults of the app: no refetch on focus or reconnect (a hook that needs fresh data opts in with its own
+ * refreshInterval), duplicate requests collapsed for a minute, at most two retries of a failing key, and no stale data
+ * across a key change (the loading state shows instead).
+ */
+const SWR_DEFAULTS = {
+    revalidateOnFocus: false,
+    revalidateOnReconnect: false,
+    dedupingInterval: 60_000,
+    errorRetryCount: 2,
+    keepPreviousData: false,
+} as const
+
+/** The app-wide session effect: modules/auth's session kept in redux. Renders nothing. */
+const AuthSessionEffect = () => {
+    useAuthSessionEffect()
+    return null
+}
+
+/**
+ * The one client provider stack the locale layout mounts, outer to inner: the theme (light and dark through the `.light` /
+ * `.dark` class the grammar and the brand layer read, the system theme by default), the redux store, the SWR defaults, the
+ * app-wide effects and the HeroUI toast region modules/toast writes to. Each part is composed here, in its one owner.
+ */
+export const AppProviders = (props: AppProvidersProps) => (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+        <ReduxProvider>
+            <SWRConfig value={SWR_DEFAULTS}>
+                <AuthSessionEffect />
+                <SwrSideEffects />
+                {props.children}
+                <ToastProvider />
+            </SWRConfig>
+        </ReduxProvider>
+    </ThemeProvider>
+)

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/index.ts

@@ -0,0 +1,4 @@
+export { useSession } from "./useSession"
+export { useSignIn } from "./useSignIn"
+export type { SignInFailure } from "./useSignIn"
+export { useSignOut } from "./useSignOut"

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSession.ts

@@ -0,0 +1,6 @@
+"use client"
+
+import { useAppSelector } from "@/redux"
+
+/** The reader's session as the app shares it (redux, kept by the auth session effect): unknown, signed in or signed out. */
+export const useSession = () => useAppSelector((state) => state.session)

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignIn.ts

@@ -0,0 +1,29 @@
+"use client"
+
+import { useState, useTransition } from "react"
+import { authClient } from "@/modules/auth"
+
+/** Why a sign-in failed: refused credentials, rejected input or the provider unavailable. */
+export type SignInFailure = "refused" | "invalid" | "unavailable"
+
+/** The failure kinds modules/auth answers; any other kind reads as the provider being unavailable. */
+const FAILURES: readonly SignInFailure[] = ["refused", "invalid", "unavailable"]
+
+/** The failure of a sign-in's failure kind. */
+const failureOf = (kind: string): SignInFailure => FAILURES.find((each) => each === kind) ?? "unavailable"
+
+/**
+ * Signs the reader in with an email and a password through modules/auth: whether a request runs, why the last one failed,
+ * the sign-in itself and `reject` for input the form could not read. A success needs no state here: the session effect
+ * moves the reader to signed in.
+ */
+export const useSignIn = () => {
+    const [failure, setFailure] = useState<SignInFailure>()
+    const [pending, startTransition] = useTransition()
+    const signIn = (email: string, password: string) =>
+        startTransition(async () => {
+            const failed = await authClient.signInWithPassword(email, password)
+            setFailure(failed === undefined ? undefined : failureOf(failed.kind))
+        })
+    return { failure, pending, signIn, reject: () => setFailure("invalid") }
+}

package/templates/fe/skeleton/apps/__app__/src/hooks/auth/useSignOut.ts

@@ -0,0 +1,27 @@
+"use client"
+
+import { useTransition } from "react"
+import type { GraphQLResponse } from "@/modules/api"
+import { authClient } from "@/modules/auth"
+import type { AuthFailure } from "@/modules/auth"
+import { useGraphQLWithToast } from "@/modules/toast"
+
+/** The app's one outcome of an auth call, so modules/toast reports it like any other write. */
+const responseOf = (failure: AuthFailure | undefined): GraphQLResponse<null> =>
+    failure === undefined
+        ? { success: true, data: null }
+        : { success: false, error: failure.code, kind: failure.kind, message: failure.message }
+
+/**
+ * Ends the reader's session through modules/auth: whether the request runs and the sign-out itself. A failure is reported by
+ * modules/toast; a success needs no toast, the session effect moves the reader to signed out.
+ */
+export const useSignOut = () => {
+    const withToast = useGraphQLWithToast()
+    const [pending, startTransition] = useTransition()
+    const signOut = () =>
+        startTransition(async () => {
+            await withToast(async () => responseOf(await authClient.signOut()), { showSuccessToast: false })
+        })
+    return { pending, signOut }
+}

package/templates/fe/skeleton/apps/__app__/src/hooks/effects/index.ts

@@ -0,0 +1 @@
+export { useAuthSessionEffect } from "./useAuthSessionEffect"

package/templates/fe/skeleton/apps/__app__/src/hooks/effects/useAuthSessionEffect.ts

@@ -0,0 +1,14 @@
+"use client"
+
+import { useEffect } from "react"
+import { authClient } from "@/modules/auth"
+import { sessionChanged, useAppDispatch } from "@/redux"
+
+/**
+ * Keeps the redux session slice equal to modules/auth by subscribing to its session events: the subscription reports the
+ * session the reader has now, then every change. It starts no load of its own; the unsubscribe ends it.
+ */
+export const useAuthSessionEffect = (): void => {
+    const dispatch = useAppDispatch()
+    useEffect(() => authClient.onChange((session) => dispatch(sessionChanged(session))), [dispatch])
+}

package/templates/fe/skeleton/apps/__app__/src/hooks/swr/SwrSideEffects.tsx

@@ -0,0 +1,8 @@
+"use client"
+
+/**
+ * The mount point of the SWR queries that run app-wide for their side effect (hydrating redux as the route or the session
+ * changes) and have no component of their own. It renders nothing, so a query that changes re-renders only this
+ * component. A new app-wide query hook (hooks/swr/api/graphql/queries/useQuery*Swr) is called here.
+ */
+export const SwrSideEffects = () => null

package/templates/fe/skeleton/apps/__app__/src/hooks/swr/index.ts

@@ -0,0 +1 @@
+export { SwrSideEffects } from "./SwrSideEffects"

package/templates/fe/skeleton/apps/__app__/src/modules/api/graphql/index.ts

@@ -0,0 +1 @@
+export type { GraphQLResponse } from "./types"

package/templates/fe/skeleton/apps/__app__/src/modules/api/graphql/types.ts

@@ -0,0 +1,26 @@
+/** A successful operation: the value the hook hands its caller. */
+export interface GraphQLSuccess<TData> {
+    readonly success: true
+    readonly data: TData
+}
+
+/**
+ * A failed operation: the stable code the back end answered (`extensions.code`), how it travels (`extensions.kind`:
+ * `unauthenticated` and `forbidden` are the refusals) and the localized message. A transport failure (network, timeout,
+ * abort) is `TRANSPORT_FAILED` of kind `unavailable`.
+ */
+export interface GraphQLFailure {
+    readonly success: false
+    readonly error: string
+    readonly kind: string
+    readonly message: string
+}
+
+/** The one outcome every operation of modules/api/graphql answers; components and hooks never see an Apollo result. */
+export type GraphQLResponse<TData> = GraphQLSuccess<TData> | GraphQLFailure
+
+/** What one operation function takes: its request and the abort signal SWR hands the fetcher. */
+export interface OperationParams<TRequest> {
+    readonly request: TRequest
+    readonly signal?: AbortSignal
+}

package/templates/fe/skeleton/apps/__app__/src/modules/api/index.ts

@@ -0,0 +1 @@
+export type { GraphQLResponse } from "./graphql"

package/templates/fe/skeleton/apps/__app__/src/modules/auth/client.ts

@@ -0,0 +1,21 @@
+import type { AuthClient, AuthFailure } from "./contracts"
+
+/** The failure of every sign-in until the app wires its identity provider. */
+const NOT_CONFIGURED: AuthFailure = { code: "AUTH_PROVIDER_NOT_CONFIGURED", kind: "unavailable", message: "" }
+
+/**
+ * The identity-provider client of a full app: a stub with the interface every edition shares, answering "no session" until
+ * the app wires its IdP (OIDC with PKCE in the browser). Replace the bodies, never the interface: the Apollo links, the
+ * session effect and the sign-in surfaces read only AuthClient.
+ */
+export const authClient: AuthClient = {
+    session: () => Promise.resolve(undefined),
+    accessToken: () => Promise.resolve(undefined),
+    refreshAccessToken: () => Promise.resolve(undefined),
+    signInWithPassword: () => Promise.resolve(NOT_CONFIGURED),
+    signOut: () => Promise.resolve(undefined),
+    onChange: (listener) => {
+        listener(undefined)
+        return () => undefined
+    },
+}

package/templates/fe/skeleton/apps/__app__/src/modules/auth/contracts.ts

@@ -0,0 +1,27 @@
+/** The signed-in reader as the identity provider states it; the back end verifies the access token on every call. */
+export interface AuthSession {
+    readonly userId: string
+    readonly email?: string
+}
+
+/** Why a sign-in or sign-out failed: the provider's code, its kind (`refused`, `invalid`, `unavailable`) and its message. */
+export interface AuthFailure {
+    readonly code: string
+    readonly kind: string
+    readonly message: string
+}
+
+/**
+ * The identity-provider client of the app, the same interface in every edition: the session, the access token the Apollo
+ * link attaches, one forced refresh for the UNAUTHENTICATED replay, the sign-in and sign-out calls (each answers its failure,
+ * or undefined when it succeeded) and a change listener that reports the current session on subscribe, then every change.
+ * It never reads or writes application data; data goes through modules/api.
+ */
+export interface AuthClient {
+    session(): Promise<AuthSession | undefined>
+    accessToken(): Promise<string | undefined>
+    refreshAccessToken(): Promise<string | undefined>
+    signInWithPassword(email: string, password: string): Promise<AuthFailure | undefined>
+    signOut(): Promise<AuthFailure | undefined>
+    onChange(listener: (session: AuthSession | undefined) => void): () => void
+}

package/templates/fe/skeleton/apps/__app__/src/modules/auth/index.ts

@@ -0,0 +1,2 @@
+export { authClient } from "./client"
+export type { AuthFailure, AuthSession } from "./contracts"

package/templates/fe/skeleton/apps/__app__/src/modules/toast/api.ts

@@ -0,0 +1,52 @@
+import type { GraphQLResponse } from "@/modules/api"
+import { toast } from "./toast"
+
+/** The localized labels of the toasts; the use*WithToast hooks resolve them from the catalog. */
+export interface ToastMessages {
+    readonly successTitle: string
+    readonly errorTitle: string
+    readonly unauthorizedTitle: string
+    readonly unauthorizedDescription: string
+    readonly defaultSuccess: string
+    readonly defaultError: string
+}
+
+/** What a run*WithToast call takes besides the labels. */
+export interface RunWithToastOptions {
+    /** Toast a success too (default true); an error is always toasted. */
+    readonly showSuccessToast?: boolean
+    /** The success description instead of the default one. */
+    readonly successMessage?: string
+}
+
+/** True when the failure is a refusal of the caller (kind `unauthenticated` or `forbidden`). */
+const isRefusal = (kind: string): boolean => kind === "unauthenticated" || kind === "forbidden"
+
+/** Toasts one GraphQLResponse: the success description, the refusal or the localized failure message. */
+export const showGraphQLToast = <T>(
+    response: GraphQLResponse<T>,
+    messages: ToastMessages,
+    options: RunWithToastOptions = {},
+): void => {
+    if (response.success) {
+        if (options.showSuccessToast !== false)
+            toast.success(messages.successTitle, { description: options.successMessage ?? messages.defaultSuccess })
+        return
+    }
+    if (isRefusal(response.kind)) {
+        toast.danger(messages.unauthorizedTitle, { description: messages.unauthorizedDescription })
+        return
+    }
+    toast.danger(messages.errorTitle, { description: response.message || messages.defaultError })
+}
+
+/** Runs one GraphQL operation and toasts its outcome; answers the response so the caller can branch on it. */
+export const runGraphQLWithToast = async <T>(
+    action: () => Promise<GraphQLResponse<T>>,
+    messages: ToastMessages,
+    options: RunWithToastOptions = {},
+): Promise<GraphQLResponse<T>> => {
+    const response = await action()
+    showGraphQLToast(response, messages, options)
+    return response
+}

package/templates/fe/skeleton/apps/__app__/src/modules/toast/hooks.ts

@@ -0,0 +1,33 @@
+"use client"
+
+import { useTranslations } from "next-intl"
+import { useCallback, useMemo } from "react"
+import type { GraphQLResponse } from "@/modules/api"
+import { runGraphQLWithToast } from "./api"
+import type { RunWithToastOptions, ToastMessages } from "./api"
+
+/** The toast labels of the reader's locale (catalog namespace `app.toast`). */
+const useToastMessages = (): ToastMessages => {
+    const t = useTranslations("app.toast")
+    return useMemo(
+        () => ({
+            successTitle: t("successTitle"),
+            errorTitle: t("errorTitle"),
+            unauthorizedTitle: t("unauthorizedTitle"),
+            unauthorizedDescription: t("unauthorizedDescription"),
+            defaultSuccess: t("defaultSuccess"),
+            defaultError: t("defaultError"),
+        }),
+        [t],
+    )
+}
+
+/** A localized runGraphQLWithToast: every GraphQL write reports its outcome through it. */
+export const useGraphQLWithToast = () => {
+    const messages = useToastMessages()
+    return useCallback(
+        <T>(action: () => Promise<GraphQLResponse<T>>, options?: RunWithToastOptions) =>
+            runGraphQLWithToast(action, messages, options),
+        [messages],
+    )
+}

package/templates/fe/skeleton/apps/__app__/src/modules/toast/index.ts

@@ -0,0 +1 @@
+export { useGraphQLWithToast } from "./hooks"