Initial commit

packages/types/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@dwellops/types",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "@types/node": "catalog:",
+    "@dwellops/config": "workspace:*"
+  }
+}

packages/types/src/auth.ts

@@ -0,0 +1,55 @@
+import type { UserId } from './common';
+
+/**
+ * HOA roles available within the platform.
+ * Ordered from most to least privileged.
+ */
+export type HoaRole = 'ADMIN' | 'BOARD_MEMBER' | 'TREASURER' | 'OWNER' | 'TENANT' | 'VIEWER';
+
+/**
+ * Resolved user identity after authentication.
+ */
+export interface AuthUser {
+    id: UserId;
+    email: string;
+    name: string | null;
+    emailVerified: boolean;
+    image: string | null;
+}
+
+/**
+ * Permission check context — identifies which HOA and unit the user is operating in.
+ */
+export interface PermissionContext {
+    userId: UserId;
+    hoaId: string;
+    role: HoaRole;
+    unitId?: string;
+}
+
+/**
+ * Auth session as surfaced to request context.
+ */
+export interface RequestSession {
+    user: AuthUser;
+    sessionId: string;
+    expiresAt: Date;
+}
+
+/**
+ * Magic link request payload.
+ */
+export interface MagicLinkRequest {
+    email: string;
+    redirectTo?: string;
+}
+
+/**
+ * OIDC provider configuration (for optional self-hosted OIDC support).
+ */
+export interface OidcProviderConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+}

packages/types/src/common.ts

@@ -0,0 +1,52 @@
+/**
+ * Generic paginated result container.
+ *
+ * @template T - The type of items in the page.
+ */
+export interface PaginatedResult<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+}
+
+/**
+ * Standard pagination query parameters.
+ */
+export interface PaginationParams {
+    page?: number;
+    pageSize?: number;
+}
+
+/**
+ * Generic API error response shape.
+ */
+export interface ApiErrorResponse {
+    statusCode: number;
+    code: string;
+    message: string;
+    details?: unknown;
+}
+
+/**
+ * Generic success response wrapper.
+ *
+ * @template T - The type of the response data.
+ */
+export interface ApiSuccessResponse<T> {
+    data: T;
+}
+
+/** ISO 8601 date string. */
+export type ISODateString = string;
+
+/** Opaque branded type helper. */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+
+/** Branded string IDs to prevent accidental mixing of ID types. */
+export type UserId = Brand<string, 'UserId'>;
+export type HoaId = Brand<string, 'HoaId'>;
+export type UnitId = Brand<string, 'UnitId'>;
+export type MembershipId = Brand<string, 'MembershipId'>;
+export type AuditLogId = Brand<string, 'AuditLogId'>;

packages/types/src/hoa.ts

@@ -0,0 +1,59 @@
+import type { HoaId, ISODateString, MembershipId, UnitId, UserId } from './common';
+import type { HoaRole } from './auth';
+
+/** HOA record. */
+export interface Hoa {
+    id: HoaId;
+    name: string;
+    slug: string;
+    description: string | null;
+    createdAt: ISODateString;
+    updatedAt: ISODateString;
+}
+
+/** Individual unit within an HOA. */
+export interface Unit {
+    id: UnitId;
+    hoaId: HoaId;
+    identifier: string;
+    address: string | null;
+    createdAt: ISODateString;
+    updatedAt: ISODateString;
+}
+
+/** User membership in an HOA with an assigned role and optional unit. */
+export interface Membership {
+    id: MembershipId;
+    userId: UserId;
+    hoaId: HoaId;
+    unitId: UnitId | null;
+    role: HoaRole;
+    createdAt: ISODateString;
+    updatedAt: ISODateString;
+}
+
+/** Audit log entry. */
+export interface AuditLogEntry {
+    id: string;
+    userId: UserId | null;
+    action: string;
+    entityType: string;
+    entityId: string | null;
+    payload: unknown;
+    ipAddress: string | null;
+    userAgent: string | null;
+    createdAt: ISODateString;
+}
+
+/** Audit-able actions. */
+export type AuditAction =
+    | 'user.created'
+    | 'user.updated'
+    | 'user.deleted'
+    | 'membership.created'
+    | 'membership.updated'
+    | 'membership.deleted'
+    | 'hoa.created'
+    | 'hoa.updated'
+    | 'unit.created'
+    | 'unit.updated';

packages/types/src/index.ts

@@ -0,0 +1,3 @@
+export * from './common';
+export * from './auth';
+export * from './hoa';

packages/types/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@dwellops/config/tsconfig/base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": true
+  },
+  "include": ["src"]
+}