npm - gymmonk-schema - Versions diffs - 0.1.3 → 0.2.0 - Mend

gymmonk-schema 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (558) hide show

package/README.md CHANGED Viewed

@@ -1,642 +1,43 @@
-# 🏋️ gymmonk-schema
+# gymmonk-schema
-> Central Zod v4 schema library for the GymMonk / Gym SaaS ecosystem.
+Shared **Zod** schemas, enums and domain types for **GymMonk** (fitness SaaS).
+Single source of truth (SSOT) consumed by both `gymmonk-backend` and
+`gymmonk-web-client`, so validation, wire types and enums never drift between
+the API and the app.
-[![npm version](https://img.shields.io/npm/v/gymmonk-schema.svg)](https://www.npmjs.com/package/gymmonk-schema)
-[![License](https://img.shields.io/npm/l/gymmonk-schema.svg)](https://github.com/yourorg/gymmonk-schema/blob/main/LICENSE)
+## What's inside
----
+- **Common** (`common.ts`) — reusable primitives: `objectIdSchema`,
+  `paginationSchema`, `optionalTrimmedString`, `emptyStringToUndefined`.
+- Domain modules (workouts, training library, membership, check-in, …) are
+  added here as they land, each re-exported through `src/index.ts`.
-## 📋 Table of Contents
-- [Overview](#overview)
-- [Installation](#installation)
-- [Core Concepts](#core-concepts)
-  - [Schemas vs Types](#schemas-vs-types)
-  - [Naming Conventions](#naming-conventions)
-- [Library Structure](#library-structure)
-  - [Common](#common)
-  - [Auth](#auth)
-  - [Gym](#gym)
-  - [Workout](#workout)
-  - [Nutrition](#nutrition)
-  - [Subscription](#subscription)
-  - [Marketing](#marketing)
-  - [Notification](#notification)
-  - [Community](#community)
-  - [Feedback](#feedback)
-  - [Support](#support)
-  - [Landing](#landing)
-  - [Audit](#audit)
-- [How to Import](#how-to-import)
-- [Usage Examples](#usage-examples)
-  - [Backend (Express)](#backend-express)
-  - [Frontend (Next.js)](#frontend-nextjs)
-  - [Forms (React Hook Form + Zod)](#forms-react-hook-form--zod)
-  - [API-doc / OpenAPI](#api-doc--openapi)
-- [Development & Publishing](#development--publishing)
-- [Versioning](#versioning)
----
-## 🎯 Overview
-This package is the **single source of truth** for:
-- ✅ Domain models (`User`, `Organisation`, `Center`, `Membership`, `Workout`, etc.)
-- ✅ API DTOs (create/update payloads)
-- ✅ Public view models (safe objects to send to frontend)
-- ✅ Shared primitives (`ObjectId`, dates, pagination, etc.)
-### 🚀 Designed for Multi-Platform Use
-It is designed to be used by:
-- **Backend** (Node.js / Express)
-- **Web frontend** (Next.js)
-- **Mobile app** (React Native)
-- **API-doc project** (OpenAPI/Swagger via zod-to-openapi)
-So all layers share the same contracts.
----
-## 📦 Installation
-In any consumer project (backend, web, app, api-doc):
-```bash
-npm install gymmonk-schema
-# or
-yarn add gymmonk-schema
-# or
-pnpm add gymmonk-schema
-```
----
-## 💡 Core Concepts
-### Schemas vs Types
-Each entity is represented by a **Zod schema** and a corresponding **TypeScript type**:
-```typescript
-import { z } from "zod";
-export const RoleSchema = z.object({
-  name: z.string().min(1),
-  description: z.string().trim().optional(),
-  permissions: z.array(z.string()).default([]),
-});
-export type Role = z.infer<typeof RoleSchema>;
-```
-#### Two Different Layers
-| Layer                     | Description                                                                                                        |
-| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| **Schema** (`RoleSchema`) | • Real runtime object<br>• Validates and parses data<br>• Used in controllers, services, forms, API-doc generation |
-| **Type** (`Role`)         | • Compile-time only (erased at runtime)<br>• Used by TypeScript for static checking and autocomplete               |
-You will see this pattern throughout the library.
-### Naming Conventions
-Inside each domain:
-- **Schemas** are named: `XxxSchema`
-- **Types** are named: `Xxx` (via `z.infer<typeof XxxSchema>`)
-- **DTOs** (request/response payloads) are named: `XxxCreateDtoSchema`, `XxxUpdateDtoSchema`, etc.
-- **Public view models** (safe to send to frontend): `PublicXxxSchema`, `type PublicXxx`
----
-## 🏗️ Library Structure
-At the top level, the package exposes namespaced domains:
-```typescript
-import {
-  Common,
-  Auth,
-  Gym,
-  Workout,
-  Nutrition,
-  Subscription,
-  Marketing,
-  Notification,
-  Community,
-  Feedback,
-  Support,
-  Landing,
-  Audit,
-} from "gymmonk-schema";
-```
-Each domain has its own folder + barrel file and follows the same structure: schemas + types grouped by feature.
-Below is an overview of what each domain represents.
----
-### 🔧 Common
-Building blocks used everywhere.
-#### Includes:
-**Primitives**
-- `ObjectIdSchema`
-- `IsoDateStringSchema`
-- `IsoDateTimeStringSchema`
-- `NonEmptyStringSchema`, `OptionalStringSchema`, etc.
-**Value Objects**
-- `EmailSchema`
-- `PhoneSchema`
-- `AddressSchema`
-- `NutritionalValuesSchema`
-- `PlanVariantSchema` (for flexible pricing options)
-- `MfaSchema`, `SocialLoginSchema`, etc.
-**Enums**
-- Gender enum
-- EntityStatus enum
-- NotificationType enum
-**Pagination**
-- `PaginationSchema` (common page, limit, etc.)
-#### Usage Example
-```typescript
-const id = Common.Primitives.ObjectIdSchema.parse(someString);
-const pagination = Common.Pagination.PaginationSchema.parse(req.query);
-```
-> ℹ️ _Exact nested names may vary slightly; check `src/common/index.ts` for the authoritative exports._
----
-### 🔐 Auth
-Authentication & authorization related models.
-#### Includes (names representative):
-- `UserSchema`, `PublicUserSchema`, `UserRegisterDtoSchema` etc.
-- `RoleSchema` (RBAC roles)
-- `PermissionSchema` (fine-grained permissions)
-- `ResourceSchema` (RBAC resources)
-- `TokenSchema` (access/refresh tokens, device tokens)
-- `OtpSchema` (one-time passwords)
-- `DeviceSchema`
-- `PasswordHistorySchema`
-- `UserActivitySchema` (login, logout, etc.)
-#### Common Usage:
-- **Backend**: validate incoming auth requests (register, login, password reset)
-- **Frontend**: type-safe forms for login/register, and PublicUser types for UI
----
-### 🏢 Gym
-All gym/organisation/center management models.
-#### Includes:
-**Organisation / Centers**
-- `OrganisationSchema`
-- `CenterSchema`
-- `CenterFacilitySchema`
-- `CenterServiceSchema`
-**Catalogs**
-- `EquipmentCatalogSchema`
-- `FacilityCatalogSchema`
-- `ServiceCatalogSchema`
-**Operational Models**
-- `AttendanceSchema`
-- `ClassScheduleSchema`
-- `EquipmentInventorySchema`
-- `GymLayoutSchema`
-- `SessionBookingSchema`
-- `GoalSchema`
-- `AchievementBadgeSchema`
-#### Used to Define and Validate:
-- How the gym, centers, facilities, services are modeled
-- Attendance tracking
-- Booking / layout / goals / badges
----
-### 💪 Workout
-Exercise and workout planning & tracking.
-#### Includes:
-- `ExerciseSchema` (name, muscle groups, media, equipment)
-- `WorkoutPlanSchema` (list of exercises with sets/reps/duration)
-- `WorkoutTrackingEntrySchema` (what a member actually did, per set, per day)
-#### Used By:
-- **Backend**: workout CRUD, tracking endpoints
-- **Frontend/App**: typed workout UI, tracking screens
----
-### 🥗 Nutrition
-Ingredient, recipes, diet plans, hydration.
-#### Includes:
-- `IngredientSchema`
-- `RecipeSchema`, `RecipeIngredientSchema`
-- `DietPlanSchema`, `DietPlanMealSchema`, `DietPlanItemSchema`
-- `DietTrackingEntrySchema`
-- `HydrationTrackingSchema`
-#### Use This For:
-- Building diet plans and logging diets
-- Aggregating nutrition
-- Hydration tracking
----
-### 💳 Subscription
-Subscription, membership, coupons, payments.
-#### Includes:
-- `SubscriptionPlanSchema`
-- `SubscriptionSchema`
-- `MembershipPlanSchema`
-- `MembershipSchema`
-- `CouponSchema`
-- `PaymentTransactionSchema`
-#### Used For:
-- Defining product plans and membership plans
-- Linking members to plans (Membership, Subscription)
-- Applying coupons and tracking payments
----
-### 📢 Marketing
-Branding, ads, campaigns, referrals.
-#### Includes:
-- `BrandSchema`
-- `AdvertisementSchema`
-- `MarketingCampaignSchema`
-- `ReferralSchema`
-#### Used For:
-- Dashboard banners, campaigns, referral systems
-- Representing marketing data in a unified way
----
-### 🔔 Notification
-Notifications and templates.
-#### Includes:
-- `NotificationSchema` (delivered notification entries)
-- `NotificationTemplateSchema` (reusable templates per channel)
-**Supports channels like**: `in_app`, `push`, `email`, `sms`.
----
-### 👥 Community
-Internal community / communication layer.
-#### Includes:
-- `ConversationSchema`
-- `MessageSchema`
-- `PostSchema`
-#### Used For:
-- Chats
-- Group conversations
-- Community posts
----
-### 💬 Feedback
-User feedback, bug reports, ratings.
-#### Includes:
-- `FeedbackSchema` (type, message, metadata, rating)
----
-### 🎫 Support
-Support tickets.
-#### Includes:
-- `SupportTicketSchema` (priority, status, category, assignments, metadata)
----
-### 🌐 Landing
-Contact requests from marketing/landing pages.
-#### Includes:
-- `ContactRequestSchema` (name, email/phone, subject, message, metadata)
----
-### 📝 Audit
-Audit logs.
-#### Includes:
-- `AuditLogSchema` (who, what, when, before/after, metadata)
----
-## 📥 How to Import
-### Top-Level Domains (Recommended)
-Prefer importing from the root in most cases:
-```typescript
-import {
-  Auth,
-  Gym,
-  Subscription,
-  Workout,
-  Nutrition,
-  Common,
-} from "gymmonk-schema";
-// Auth
-const dto = Auth.UserRegisterDtoSchema.parse(body);
-// Gym
-const center = Gym.CenterSchema.parse(payload);
-// Subscription
-type Plan = Subscription.SubscriptionPlan;
-const planSchema = Subscription.SubscriptionPlanSchema;
-```
-> 💡 If you want very fine-grained imports, you can also import directly from subpaths as long as your build/exports are configured for it (check your `package.json` "exports" if you add that later).
----
-## 🎨 Usage Examples
-### Backend (Express)
-#### Validate Request Body (DTO)
-```typescript
-import { Auth } from "gymmonk-schema";
-import type { Request, Response } from "express";
-export async function registerHandler(req: Request, res: Response) {
-  try {
-    const dto = Auth.UserRegisterDtoSchema.parse(req.body);
-    // dto is fully validated and typed
-    const user = await createUser(dto);
-    const publicUser = Auth.PublicUserSchema.parse(user);
-    return res.status(201).json(publicUser);
-  } catch (err: any) {
-    return res.status(400).json({
-      message: "Invalid request",
-      errors: err.errors ?? err,
-    });
-  }
-}
-```
-#### Validate Query Params
-```typescript
-import { Common } from "gymmonk-schema";
-app.get("/centers", (req, res) => {
-  const pagination = Common.Pagination.PaginationSchema.parse(req.query);
-  // use pagination.page / pagination.limit
-});
-```
----
-### Frontend (Next.js)
-#### Validate Data Before Sending to Backend
-```typescript
-"use client";
-import { Auth } from "gymmonk-schema";
-async function submit(formData: any) {
-  const dto = Auth.UserRegisterDtoSchema.parse(formData);
-  const res = await fetch("/api/auth/register", {
-    method: "POST",
-    body: JSON.stringify(dto),
-    headers: { "Content-Type": "application/json" },
-  });
-  return res.json();
-}
-```
-#### Strongly Typed UI Components
-```typescript
-import { Gym } from "gymmonk-schema";
-type Center = Gym.Center;
-function CenterCard({ center }: { center: Center }) {
-  return (
-    <div>
-      <h2>{center.name}</h2>
-      <p>{center.address?.city}</p>
-    </div>
-  );
-}
-```
----
-### Forms (React Hook Form + Zod)
-```typescript
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { Subscription } from "gymmonk-schema";
-const schema = Subscription.SubscriptionPlanSchema;
-type PlanForm = Subscription.SubscriptionPlan;
-export function PlanFormComponent() {
-  const form = useForm<PlanForm>({
-    resolver: zodResolver(schema),
-  });
-  // form.register, form.handleSubmit, etc.
-}
-```
----
-### API-doc / OpenAPI
-In your API-doc project (contract-first design), you can introspect schemas and generate OpenAPI:
-```typescript
-import {
-  OpenAPIRegistry,
-  generateOpenApiDocument,
-} from "@asteasolutions/zod-to-openapi";
-import { Auth, Gym } from "gymmonk-schema";
-const registry = new OpenAPIRegistry();
-// Register schemas
-registry.register("User", Auth.PublicUserSchema);
-registry.register("Center", Gym.CenterSchema);
-// Register routes and use the schemas in request/response definitions…
-const openapi = generateOpenApiDocument(registry.definitions, {
-  openapi: "3.0.0",
-  info: {
-    title: "GymMonk API",
-    version: "1.0.0",
-  },
-});
-// Then write openapi.json and serve via swagger-ui-express
-```
-This way API docs are always in sync with your code and frontend types.
----
-## 🛠️ Development & Publishing
-In the `gymmonk-schema` repo:
-### Build
+## Build & publish (npm-first)
 ```bash
-npm run build
-```
-**Typical script:**
-```json
-"build": "tsc"
-```
-This compiles `src/**/*.ts` → `dist/**/*.js` + `.d.ts`.
-### Lint + Format
-Using Biome:
-```bash
-npm run check      # type-check + lint + format (depending on your script)
-npm run lint       # if you have a separate lint script
-npm run format     # if you have a separate format script
-```
-### Version Bump
-Use semantic versioning:
-```bash
-npm version patch   # 0.1.0 -> 0.1.1
-npm version minor   # 0.1.0 -> 0.2.0
-npm version major   # 0.1.0 -> 1.0.0
+npm install
+npm run build          # tsc -> dist/
+npm publish --access public
 ```
-This updates `package.json` and creates a git commit + tag (if configured).
+`prepublishOnly` runs `build` + `check` (type-check + biome) as the publish gate.
+`--access public` is a CLI flag, not a manifest field.
-### Publish
+## Consume
-```bash
-npm login
-npm run build
-npm publish --access public
-```
-Then consumers can install:
+In `gymmonk-backend` and `gymmonk-web-client`:
 ```bash
-npm install gymmonk-schema
+npm install gymmonk-schema@<version>
+# then delete any nested Zod dup so a single Zod instance is used:
+rm -rf node_modules/gymmonk-schema/node_modules
 ```
----
-## 📌 Versioning
-Follow standard **SemVer**:
-| Version Type | Pattern | Description                                                      |
-| ------------ | ------- | ---------------------------------------------------------------- |
-| **PATCH**    | `x.y.Z` | Internal fixes, no breaking changes                              |
-| **MINOR**    | `x.Y.z` | New schemas/fields added in a backwards-compatible way           |
-| **MAJOR**    | `X.y.z` | Breaking changes (removed fields, renamed, incompatible changes) |
-### Guidelines:
-- ✅ **Adding optional fields**: minor
-- ⚠️ **Making a field required or changing its type**: major
-- ⚠️ **Removing schemas or renaming them**: major
-> 📝 Keep a simple `CHANGELOG.md` to track what changed between versions, especially when schemas or DTOs change in ways that affect consumers.
----
-<div align="center">
+Bump the caret pin in each consumer's `package.json` on every publish (a `0.x`
+caret locks to the same minor, so `npm install` won't auto-pick a new minor).
-**Built with ❤️ for the GymMonk ecosystem**
+## Convention
-</div>
+Mirrors the jansathi schema family (`dating-schema`, `near-me-schema`) exactly:
+pure ESM, `tsc`-only build, Zod is a **peer** dependency (`^4.4.0`), NodeNext
+`.js` import specifiers, const-object enums fed to `z.enum(...)`.

package/dist/common.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+/**
+ * gymmonk-schema — Shared helpers and primitives
+ * ==============================================
+ * The stable building blocks reused across every GymMonk domain schema.
+ * Mirrors the `dating-schema` / `near-me-schema` idiom: pure Zod, const-object
+ * enums fed to `z.enum(...)`, NodeNext `.js` import specifiers.
+ *
+ * @module gymmonk-schema/common
+ */
+import { z } from 'zod';
+/**
+ * Converts empty / whitespace-only strings to `undefined`
+ * so Zod `.optional()` treats them as "not provided".
+ */
+export declare const emptyStringToUndefined: (value: unknown) => unknown;
+/** Optional trimmed string. Empty strings are coerced to `undefined`. */
+export declare const optionalTrimmedString: (maxLength?: number) => z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+/** A 24-character hex MongoDB ObjectId string. */
+export declare const objectIdSchema: z.ZodString;
+export type ObjectIdString = z.infer<typeof objectIdSchema>;
+/** Pagination query params shared across list endpoints. */
+export declare const paginationSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type Pagination = z.infer<typeof paginationSchema>;
+//# sourceMappingURL=common.d.ts.map

package/dist/common.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,OAAO,KAAG,OAGvD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,GAAI,kBAAe,gDAC8B,CAAC;AAIpF,kDAAkD;AAClD,eAAO,MAAM,cAAc,aAGgB,CAAC;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAI5D,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB;;;iBAG3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC"}