create-nexwire 4.2.3 → 4.2.5

package/express/src/framework/providers/contracts.ts

@@ -1,6 +1,6 @@
 /**
  * Why: Defines the shapes a pluggable provider has to satisfy.
- * When: A developer replaces a framework default (auth today, payments later).
+ * When: A developer replaces a framework default (auth, notifications, payments later).
  * Where: Imported through the framework facade, never from framework internals.
  * How: Interfaces stay deliberately loose so custom user shapes pass through.
  */
@@ -8,6 +8,9 @@
 /** Registry key of the built-in auth provider contract. */
 export const AUTH_PROVIDER_KEY = "auth";
 
+/** Registry key of the built-in notification storage provider. */
+export const NOTIFICATION_PROVIDER_KEY = "notification";
+
 /**
  * Registry key for any provider implementation.
  *
@@ -15,25 +18,25 @@ export const AUTH_PROVIDER_KEY = "auth";
  * still accepting any custom key, so a project can register its own contracts
  * (payments, otp, storage, ...) without the framework having to know them.
  */
-export type ProviderKey = typeof AUTH_PROVIDER_KEY | (string & {});
+export type ProviderKey = typeof AUTH_PROVIDER_KEY | typeof NOTIFICATION_PROVIDER_KEY | (string & {});
 
 export interface AuthProviderUser {
-  id: number;
+  id: number | string;
   email?: string | null;
   [key: string]: any;
 }
 
 export interface AuthProviderRefreshToken {
-  id: number;
+  id: number | string;
   jti: string;
   revoked?: boolean | null;
   expiresAt?: Date | string | null;
-  userId?: number | null;
+  userId?: number | string | null;
   [key: string]: any;
 }
 
 export interface AuthUserContext {
-  id: number;
+  id: number | string;
   email?: string | null;
   roleId?: number | null;
   role?: string | null;
@@ -47,10 +50,77 @@ export interface AuthUserContact {
 }
 
 export interface AuthProvider {
-  getUserById(id: number): Promise<AuthProviderUser | null>;
+  getUserById(id: number | string): Promise<AuthProviderUser | null>;
   findRefreshToken(jti: string): Promise<AuthProviderRefreshToken | null>;
-  revokeRefreshToken?(tokenId: number): Promise<void>;
-  deleteRefreshToken?(tokenId: number): Promise<void>;
+  revokeRefreshToken?(tokenId: number | string): Promise<void>;
+  deleteRefreshToken?(tokenId: number | string): Promise<void>;
   getAuthContext?(user: AuthProviderUser, payload?: any): Promise<AuthUserContext | any>;
-  getUserContact?(userId: number): Promise<AuthUserContact | null>;
+  getUserContact?(userId: number | string): Promise<AuthUserContact | null>;
+}
+
+/**
+ * Who a notification belongs to. `id` accepts a numeric auth id and a string
+ * id (UUID, ULID, ...) so replacing auth does not force a notification change.
+ * The provider always stores the id as text.
+ */
+export interface NotifiableTarget {
+  /** Notifiable class. Defaults to "user". */
+  type?: string;
+  id: number | string;
+}
+
+/** Payload accepted by `NotificationProvider.create()`. */
+export interface NotificationCreateInput {
+  type?: string;
+  title: string;
+  body?: string | null;
+  link?: string | null;
+  data?: Record<string, unknown> | null;
+}
+
+/** Normalized notification returned by every provider operation. */
+export interface NotificationRecord {
+  id: string;
+  notifiableType: string;
+  notifiableId: string;
+  type: string;
+  title: string;
+  body: string | null;
+  data: Record<string, unknown> | null;
+  link: string | null;
+  readAt: string | null;
+  createdAt: string;
+}
+
+export interface NotificationListOptions {
+  page?: number;
+  perPage?: number;
+}
+
+export interface NotificationPage {
+  data: NotificationRecord[];
+  total: number;
+  unread: number;
+  page: number;
+  perPage: number;
+}
+
+/**
+ * Why: Keeps notification storage replaceable without touching `notify()` or
+ *      the generated HTTP routes.
+ * When: The default `src/modules/notification` store is replaced by a custom
+ *       implementation (a different table, another service, ...).
+ * Where: Registered through `registerNotificationProvider()`.
+ * How: The framework only reads through this contract; mail and realtime
+ *      delivery stay in the runtime so a storage swap cannot disable them.
+ */
+export interface NotificationProvider {
+  create(target: NotifiableTarget, input: NotificationCreateInput): Promise<NotificationRecord>;
+  list(target: NotifiableTarget, options?: NotificationListOptions): Promise<NotificationPage>;
+  unreadCount(target: NotifiableTarget): Promise<number>;
+  markRead(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  markAllRead(target: NotifiableTarget): Promise<number>;
+  remove(target: NotifiableTarget, id: number | string): Promise<boolean>;
+  /** Optional bulk cleanup when a notifiable target is deleted. */
+  deleteForTarget?(target: NotifiableTarget): Promise<number>;
 }

package/express/src/framework/providers/registry.ts

@@ -1,4 +1,10 @@
-import { AUTH_PROVIDER_KEY, type AuthProvider, type ProviderKey } from "./contracts.js";
+import {
+  AUTH_PROVIDER_KEY,
+  type AuthProvider,
+  NOTIFICATION_PROVIDER_KEY,
+  type NotificationProvider,
+  type ProviderKey
+} from "./contracts.js";
 
 /**
  * Why: Holds the app-wide provider implementations in one place.
@@ -60,3 +66,23 @@ export function hasAuthProvider(): boolean {
 export function clearAuthProvider(): void {
   clearProvider(AUTH_PROVIDER_KEY);
 }
+
+/** Registers the storage provider `notify()` and `/api/notification/*` use. */
+export function registerNotificationProvider(provider: NotificationProvider): NotificationProvider {
+  return registerProvider(NOTIFICATION_PROVIDER_KEY, provider);
+}
+
+/** Returns the registered notification provider, or null when none was registered. */
+export function getNotificationProvider(): NotificationProvider | null {
+  return getProvider<NotificationProvider>(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Reports whether a notification provider is registered. */
+export function hasNotificationProvider(): boolean {
+  return hasProvider(NOTIFICATION_PROVIDER_KEY);
+}
+
+/** Removes the registered notification provider. Mainly useful in tests. */
+export function clearNotificationProvider(): void {
+  clearProvider(NOTIFICATION_PROVIDER_KEY);
+}

package/express/src/resources/src/components/Checkbox.vue

@@ -1,29 +1,32 @@
-<template>
-  <div class="form-check mb-0" :class="props.topclass">
-    <input
-      :id="String(props.id)"
-      v-model="model"
-      class="form-check-input shadow-none border-secondary"
-      type="checkbox"
-      v-bind="$attrs" />
-    <label v-if="props.label" class="form-check-label" :for="String(props.id)">{{ props.label }}</label>
-  </div>
-</template>
-
-<script setup lang="ts">
-defineOptions({ name: "Checkbox", inheritAttrs: false });
-
-interface CheckboxProps {
-  id?: string | number;
-  label?: string;
-  topclass?: string;
-}
-
-const props = defineProps<CheckboxProps>();
-
-type CheckboxModel = boolean | Array<string | number>;
-
-const model = defineModel<CheckboxModel>({ default: false });
-</script>
-
-<style lang="scss" scoped></style>
+<template>
+  <div class="form-check mb-0" :class="props.topclass">
+    <input
+      :id="String(props.id)"
+      v-model="model"
+      class="form-check-input shadow-none"
+      type="checkbox"
+      v-bind="$attrs"
+    />
+    <label v-if="props.label" class="form-check-label" :for="String(props.id)">{{
+      props.label
+    }}</label>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineOptions({ name: "Checkbox", inheritAttrs: false });
+
+interface CheckboxProps {
+  id?: string | number;
+  label?: string;
+  topclass?: string;
+}
+
+const props = defineProps<CheckboxProps>();
+
+type CheckboxModel = boolean | Array<string | number>;
+
+const model = defineModel<CheckboxModel>({ default: false });
+</script>
+
+<style lang="scss" scoped></style>