@ipetsadmin/contracts

Shared TypeScript types, enums, and error classes for Truffa projects. Published as a scoped npm package (@ipetsadmin/contracts).

Requirements

• Node.js 18.18+ (see engines in package.json)
• pnpm is used in this repo (npm/yarn work for consumers)

Installation

pnpm add @ipetsadmin/contracts
# or
npm install @ipetsadmin/contracts

For a scoped public package, publishing typically uses:

pnpm publish --access public

Configure your registry in .npmrc if you use GitHub Packages or another host.

From Git (alternative)

pnpm add git+https://github.com/your-org/contracts.git
pnpm add git+https://github.com/your-org/contracts.git#v1.0.0

Usage

import {
  AuthMethod,
  Errors,
  HealthCheck,
  HealthStatus,
  IConfig,
  IApiResponse,
  IPaginatedResponse,
  IServerInit,
  OAuthProvider,
  type AuthSessionResponse,
  type IUser,
  type LoginRequest,
  type RegisterRequest,
  type TokenPair,
  BaseError,
  BusinessError,
  ForbiddenError,
  NotFoundError,
  ServerError,
  UnauthorizedError,
} from '@ipetsadmin/contracts';

// Example: typed health-check response body
const health: IApiResponse<HealthCheck> = {
  success: true,
  message: 'API is running',
  data: { message: 'API is running', status: HealthStatus.HEALTHY },
};

Authentication and users

The package defines shared contracts for email/password and OAuth (Google via Auth0 on the server), API-issued JWTs (access) and opaque refresh tokens (server-side storage only—hashes are not part of the public types):

• Enums: AuthMethod (password | oauth), OAuthProvider (e.g. GOOGLE, extensible later).
• Entities / DTOs: IUser, TokenPair, AuthUserResponse, AuthSessionResponse, RegisterRequest, LoginRequest, RefreshRequest, LogoutRequest, OAuth Google start/callback types, CreateUserInput.
• Repository ports (implementations live in services): IUserRepository, IRefreshTokenRepository, IOAuthStateRepository — keep domain types free of MongoDB/Passport imports so SQL or other adapters can implement the same interfaces later.
• Service ports (interfaces/services/): IAuthService, IJwtTokensService, IAuth0GoogleOAuthService — implemented by the API’s concrete classes for DI, testing, and clear boundaries.
• Auth0/OIDC helpers: Auth0UserProfile, Auth0AuthorizationParams, OAuthAccessTokenResult.

IConfig includes optional fields for RS256 JWT (jwtIssuer, jwtAudience, PEM keys, TTLs), MongoDB, Auth0, and oauthAllowedRedirectUris (comma-separated allowlist for OAuth redirect URIs).

Path aliases (@/…) apply only inside this package’s source; consumers import from @ipetsadmin/contracts as above.

Pets, treatments, and doses

Shared model for veterinary pets, medication/surgery treatments, and scheduled doses (consumers: @ipetsadmin/api-main, @ipetsadmin/api-client, etc.):

| Area | Highlights | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pet | IPet: discriminated species (dog vs cat) with matching breed, demographics, PetStatus, WeightUnit, allergies, vaccines, microchip fields, photos, timestamps. PetResponse is an alias for IPet. CreatePetInput is used for IPetRepository.create / IPetService. IPetRepository: create, findById, findByOwnerId, update (partial input). IPetService: getPetById, getPetsByUserId, createPet, updatePet. | | Treatment | ITreatment (medication line, dosing schedule, TreatmentStatus / TreatmentType, optional start/end dates). CreateTreatmentInput, TreatmentResponse. ITreatmentRepository: create, update, findById, findByPetId, delete. | | Dose | IDose links treatmentId, petId, ownerId; doseNumber, scheduledDate, optional actualAdministeredDate, DoseStatus, optional notes. CreateDoseInput, DoseResponse. IDoseRepository: create, findById, findByTreatmentId, delete, deleteByTreatmentId. | | Treatment application service | ITreatmentService: createTreatment, updateTreatment, updateTreatmentStatus, getTreatmentById (treatment plus nested doses), getTreatmentsByPetId, deleteTreatment, getDosesByTreatmentId, createDose. All methods optionally accept RepositoryOperationOptions (e.g. Mongo session for transactions). |

Related enums (Species, DogBreed, CatBreed, Gender, PetStatus, WeightUnit, TreatmentStatus, TreatmentType, DoseStatus, WorkerName) live under src/enums/ and are re-exported from the package root.

Background jobs (BullMQ)

Queue names remain implementation-specific on the API, but job payloads and Worker.name strings may be shared so producers, consumers, and clients agree on types:

| Export | Purpose | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | DoseNotificationJobData | Data for dose-notification jobs (doseId, treatmentId, petId, ownerId, medicationName, doseNumber). | | WorkerName | EMAIL_NOTIFICATION_WORKER (email-notification-worker) — aligns with BullMQ Worker name in api-main. |

import {
  type CreatePetInput,
  type CreateTreatmentInput,
  type CreateDoseInput,
  type DoseNotificationJobData,
  type IPet,
  type ITreatment,
  type IDose,
  type IPetService,
  type ITreatmentService,
  WorkerName,
  PetStatus,
  TreatmentType,
  TreatmentStatus,
  DoseStatus,
} from '@ipetsadmin/contracts';

The published package is dual CJS + ESM (exports.require → dist/index.js, exports.import → dist/index.mjs). That way import { BaseError, BusinessError } from '@ipetsadmin/contracts' works in ESM projects ("type": "module", Vite, etc.), and require('@ipetsadmin/contracts') still works in CommonJS. Use TypeScript moduleResolution: "node16" or "nodenext" (or "bundler") in consuming apps so types resolve through package.json exports.

Development

Install dependencies and (on first clone) install Git hooks:

pnpm install

| Script | Description | | ----------------------- | ------------------------------------------------------------------------------------------ | | pnpm run build | tsup: bundle src/index.ts → dist/index.js (CJS) + dist/index.mjs (ESM) + .d.ts | | pnpm run clean | Remove dist/ | | pnpm run typecheck | tsc --noEmit (no emit, full typecheck) | | pnpm run lint | ESLint with cache (.eslintcache) | | pnpm run lint:fix | ESLint with --fix | | pnpm run format | Prettier write (respects .prettierignore) | | pnpm run format:check | Prettier check only | | pnpm run validate | typecheck → lint → format:check (use in CI) |

Pre-commit: Husky runs lint-staged: ESLint + Prettier on staged *.ts / *.tsx, Prettier on staged *.json / *.md.

Before publish: prepublishOnly runs validate then build, so broken code should not ship.

Tooling in this repo

• tsup — tsup.config.ts; dual CJS/ESM build for the npm entry
• ESLint — eslint.config.mjs (flat config), TypeScript type-aware rules via typescript-eslint, conflicts with Prettier disabled via eslint-config-prettier
• Prettier — .prettierrc.json, .prettierignore
• Editor defaults — .editorconfig

Publishing

1. Bump the version in package.json.
2. Run pnpm run validate and fix any issues.
3. Publish: pnpm publish (or your registry-specific command).

pnpm run build runs automatically in prepublishOnly after validate.

Package layout

Source lives under src/:

• enums/ — shared enums (Errors, HealthStatus, AuthMethod, OAuthProvider, Species, PetStatus, TreatmentStatus, TreatmentType, DoseStatus, WorkerName, …)
• errors/ — error classes (BaseError, domain errors, …)
• interfaces/entities/ — domain entities (IUser, IPet, ITreatment, IDose; nested types such as IAllergy, IVaccine on IPet)
• interfaces/general/ — cross-cutting interfaces (IConfig, pagination, API responses, server bootstrap types, …)
• interfaces/repositories/ — persistence ports (IUserRepository, IPetRepository, ITreatmentRepository, IDoseRepository, …) plus repositories/auth/ for refresh/oauth tokens
• interfaces/services/ — application service ports (IAuthService, IJwtTokensService, IAuth0GoogleOAuthService, IUserService, IPetService, ITreatmentService, email subfolder, …)
• types/ — DTOs and aliases (types/auth/, types/pet/, types/treatment/, types/dose/, types/jobs/ e.g. DoseNotificationJobData, types/user/, types/email/, HealthCheck, RepositoryOperationOptions, …)

The public API is whatever src/index.ts re-exports. Additional definitions under src/ only appear for consumers when listed there.

Serverless / private registry notes

• Private npm: set @ipetsadmin:registry=… and auth in .npmrc (or NPM_TOKEN in CI).
• Git installs: ensure deploy environments can reach the repo and run pnpm install / npm install as usual.

AWS Lambda / Serverless Framework (example)

package:
  patterns:
    - '!node_modules/**'
    - 'node_modules/@ipetsadmin/contracts/**'

Vercel

Dependencies resolve at build time; ensure registry or Git access is configured for private packages.

Changelog

Release notes live in CHANGELOG.md (Keep a Changelog).

License

See LICENSE (MIT).