@lcas58/esmi-api-types 1.0.6 → 1.0.7

package/dist/src/routes/organizations/organizations.handlers.d.ts

@@ -0,0 +1,74 @@
+import type { AppRouteHandler } from "../../lib/types.js";
+import type { CheckOrganizationNameRoute, CheckOwnershipRoute, CreateRoute, GetOneRoute, ListRoute, PatchRoute, RemoveRoute } from "./organizations.routes.js";
+/**
+ * Retrieves a single organization by ID
+ *
+ * @description Fetches an organization with all related data (tags, websites, social media).
+ * Only the organization owner can access the full details.
+ *
+ * @param c - Hono context containing request data and environment
+ * @returns Organization data with related entities or error response
+ */
+export declare const getOne: AppRouteHandler<GetOneRoute>;
+/**
+ * Lists organizations with optional filtering
+ *
+ * @description Retrieves a list of organizations with support for filtering by:
+ * - ownerId: Filter by organization owner
+ * - city, state, country: Filter by location (case-insensitive partial match)
+ *
+ * @param c - Hono context containing query parameters
+ * @returns Array of organizations with related data
+ */
+export declare const list: AppRouteHandler<ListRoute>;
+/**
+ * Creates a new organization with related data
+ *
+ * @description Creates an organization along with optional tags, websites, and social media.
+ * Uses a database transaction to ensure data consistency.
+ *
+ * @param c - Hono context containing organization data and authenticated user
+ * @returns Created organization data or error response
+ */
+export declare const create: AppRouteHandler<CreateRoute>;
+/**
+ * Updates an existing organization and its related data
+ *
+ * @description Performs partial updates to an organization including related entities.
+ * Uses replace strategy for tags, websites, and social media (delete all, insert new).
+ *
+ * @param c - Hono context containing organization ID and update data
+ * @returns Updated organization data or error response
+ */
+export declare const patch: AppRouteHandler<PatchRoute>;
+/**
+ * Deletes an organization and all related data
+ *
+ * @description Removes an organization from the database. Due to CASCADE constraints,
+ * all related data (websites, social media, tags) will be automatically deleted.
+ *
+ * @param c - Hono context containing organization ID
+ * @returns 204 No Content on success or 404 Not Found if organization doesn't exist
+ */
+export declare const remove: AppRouteHandler<RemoveRoute>;
+/**
+ * Checks if the authenticated user owns the specified organization
+ *
+ * @description Verifies ownership without returning organization data.
+ * Used for authorization checks in the frontend.
+ *
+ * @param c - Hono context containing organization ID and authenticated user
+ * @returns Ownership status (true/false) or 404 if organization doesn't exist
+ */
+export declare const checkOwnership: AppRouteHandler<CheckOwnershipRoute>;
+/**
+ * Checks if an organization name is available
+ *
+ * @description Verifies if the provided name is unique in the database.
+ * When taken, returns similar available slugs using pg_trgm similarity.
+ * Used for name validation in the frontend.
+ *
+ * @param c - Hono context containing organization name
+ * @returns Availability status and suggestions if taken
+ */
+export declare const checkOrganizationName: AppRouteHandler<CheckOrganizationNameRoute>;

package/dist/src/routes/organizations/organizations.handlers.js

@@ -0,0 +1,485 @@
+import { and, eq, ilike, sql } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
+import * as HttpStatusCodes from "stoker/http-status-codes";
+import * as HttpStatusPhrases from "stoker/http-status-phrases";
+import { closePool, createDb, createPool } from "../../db/index.js";
+import { generateSocialMediaUrl, organizationSocialMedia, organizationTags, organizationWebsites } from "../../db/schema/index.js";
+import organization from "../../db/schema/organization.js";
+import { processAvatarUpdate } from "../../lib/avatar-helpers.js";
+import { ZOD_ERROR_CODES, ZOD_ERROR_MESSAGES } from "../../lib/constants.js";
+import { slugify } from "../../lib/helpers.js";
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Transforms raw organization data from database to API response format
+ *
+ * @param organizationData - Raw organization data from database query
+ * @returns Transformed organization data for API response
+ */
+function transformOrganizationData(organizationData) {
+    return {
+        ...organizationData,
+        tags: organizationData.tags.map((t) => ({
+            id: t.tagId,
+            name: t.tag.name,
+        })),
+        websites: organizationData.websites.map((w) => ({
+            id: w.id,
+            url: w.url,
+            label: w.label || "",
+        })),
+        socialMedia: organizationData.socialMedia.map((s) => ({
+            id: s.id,
+            platform: s.platform,
+            url: s.url || "",
+            handle: s.handle,
+        })),
+    };
+}
+/**
+ * Builds location-based filters for organization queries
+ *
+ * @param city - Optional city filter (case-insensitive partial match)
+ * @param state - Optional state filter (case-insensitive partial match)
+ * @param country - Optional country filter (case-insensitive partial match)
+ * @returns Array of SQL filter conditions
+ */
+function buildLocationFilters(city, state, country) {
+    const filters = [];
+    const trimmedCity = city?.trim();
+    const trimmedState = state?.trim();
+    const trimmedCountry = country?.trim();
+    if (trimmedCity)
+        filters.push(ilike(organization.city, trimmedCity));
+    if (trimmedState)
+        filters.push(ilike(organization.state, trimmedState));
+    if (trimmedCountry)
+        filters.push(ilike(organization.country, trimmedCountry));
+    return filters;
+}
+/**
+ * Creates a where clause from an array of SQL conditions
+ *
+ * @param filters - Array of SQL filter conditions
+ * @returns Combined where clause or undefined if no filters
+ */
+function createWhereClause(filters) {
+    if (filters.length === 0)
+        return undefined;
+    if (filters.length === 1)
+        return filters[0];
+    return and(...filters);
+}
+/**
+ * Validates and trims location fields from update data
+ *
+ * @param updateData - Object containing update fields
+ * @returns Processed update data with trimmed location fields
+ */
+function processLocationUpdates(updateData) {
+    if (typeof updateData.city === "string")
+        updateData.city = updateData.city.trim();
+    if (typeof updateData.state === "string")
+        updateData.state = updateData.state.trim() || null;
+    if (typeof updateData.shortStateCd === "string")
+        updateData.shortStateCd = updateData.shortStateCd.trim() || null;
+    if (typeof updateData.country === "string")
+        updateData.country = updateData.country.trim();
+    return updateData;
+}
+/**
+ * Creates organization tags in a database transaction
+ *
+ * @param tx - Database transaction instance
+ * @param organizationId - ID of the organization
+ * @param tags - Array of tag data to create
+ */
+async function createOrganizationTags(tx, organizationId, tags) {
+    if (tags && tags.length > 0) {
+        await tx.insert(organizationTags).values(tags.map(tag => ({
+            organizationId,
+            tagId: tag.tagId,
+        })));
+    }
+}
+/**
+ * Creates organization websites in a database transaction
+ *
+ * @param tx - Database transaction instance
+ * @param organizationId - ID of the organization
+ * @param websites - Array of website data to create
+ */
+async function createOrganizationWebsites(tx, organizationId, websites) {
+    if (websites && websites.length > 0) {
+        await tx.insert(organizationWebsites).values(websites.map(website => ({
+            ...website,
+            organizationId,
+        })));
+    }
+}
+/**
+ * Creates organization social media in a database transaction
+ *
+ * @param tx - Database transaction instance
+ * @param organizationId - ID of the organization
+ * @param socialMedia - Array of social media data to create
+ */
+async function createOrganizationSocialMedia(tx, organizationId, socialMedia) {
+    if (socialMedia && socialMedia.length > 0) {
+        await tx.insert(organizationSocialMedia).values(socialMedia.map(social => ({
+            ...social,
+            organizationId,
+            // Generate URL dynamically if not provided
+            url: social.url || generateSocialMediaUrl(social.platform, social.handle),
+        })));
+    }
+}
+// =============================================================================
+// ORGANIZATION HANDLERS
+// =============================================================================
+/**
+ * Retrieves a single organization by ID
+ *
+ * @description Fetches an organization with all related data (tags, websites, social media).
+ * Only the organization owner can access the full details.
+ *
+ * @param c - Hono context containing request data and environment
+ * @returns Organization data with related entities or error response
+ */
+export const getOne = async (c) => {
+    const { db } = createDb(c.env);
+    const { id } = c.req.valid("param");
+    const authUser = c.get("user");
+    const organizationData = await db.query.organization.findFirst({
+        where: eq(organization.id, id),
+        with: {
+            tags: {
+                with: {
+                    tag: true,
+                },
+            },
+            websites: true,
+            socialMedia: true,
+        },
+    });
+    if (!organizationData) {
+        return c.json({
+            message: HttpStatusPhrases.NOT_FOUND,
+        }, HttpStatusCodes.NOT_FOUND);
+    }
+    // Check if the user owns this organization
+    if (organizationData.ownerId !== authUser.id) {
+        return c.json({
+            message: "Unauthorized",
+        }, HttpStatusCodes.UNAUTHORIZED);
+    }
+    const transformedData = transformOrganizationData(organizationData);
+    return c.json(transformedData, HttpStatusCodes.OK);
+};
+/**
+ * Lists organizations with optional filtering
+ *
+ * @description Retrieves a list of organizations with support for filtering by:
+ * - ownerId: Filter by organization owner
+ * - city, state, country: Filter by location (case-insensitive partial match)
+ *
+ * @param c - Hono context containing query parameters
+ * @returns Array of organizations with related data
+ */
+export const list = async (c) => {
+    const { db } = createDb(c.env);
+    const { ownerId, city, state, country } = c.req.valid("query");
+    const filters = [];
+    // Add owner filter if specified
+    if (ownerId)
+        filters.push(eq(organization.ownerId, ownerId));
+    // Add location filters
+    const locationFilters = buildLocationFilters(city, state, country);
+    filters.push(...locationFilters);
+    const whereClause = createWhereClause(filters);
+    const organizations = await db.query.organization.findMany({
+        where: whereClause,
+        with: {
+            tags: {
+                with: {
+                    tag: true,
+                },
+            },
+            websites: true,
+            socialMedia: true,
+        },
+    });
+    return c.json(organizations, HttpStatusCodes.OK);
+};
+/**
+ * Creates a new organization with related data
+ *
+ * @description Creates an organization along with optional tags, websites, and social media.
+ * Uses a database transaction to ensure data consistency.
+ *
+ * @param c - Hono context containing organization data and authenticated user
+ * @returns Created organization data or error response
+ */
+export const create = async (c) => {
+    const { pool, dbPool } = createPool(c.env);
+    const data = c.req.valid("json");
+    const user = c.get("user");
+    // Process avatar if provided
+    let processedAvatar;
+    if (data.avatar) {
+        // We'll generate a temporary ID for the organization to use in avatar processing
+        const tempOrgId = randomUUID();
+        const avatarResult = await processAvatarUpdate(data.avatar, tempOrgId, undefined, c.env);
+        if (!avatarResult.success) {
+            return c.json({
+                success: false,
+                error: {
+                    issues: [
+                        {
+                            code: "invalid_type",
+                            path: ["avatar"],
+                            message: avatarResult.error || "Invalid avatar",
+                        },
+                    ],
+                    name: "ZodError",
+                },
+            }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+        }
+        processedAvatar = avatarResult.avatarValue;
+    }
+    try {
+        // Use transaction to ensure all related data is created together
+        const result = await dbPool.transaction(async (tx) => {
+            // Create organization with trimmed location data
+            const [insertedOrg] = await tx.insert(organization).values({
+                name: data.name.trim(),
+                description: data.description.trim(),
+                ownerId: user.id,
+                avatar: processedAvatar,
+                slug: slugify(data.name.trim()),
+                city: data.city?.trim(),
+                state: data.state?.trim(),
+                stateCd: data.stateCd?.trim(),
+                country: data.country?.trim(),
+            }).returning();
+            // Create related data using helper functions
+            await createOrganizationTags(tx, insertedOrg.id, data.tags);
+            await createOrganizationWebsites(tx, insertedOrg.id, data.websites);
+            await createOrganizationSocialMedia(tx, insertedOrg.id, data.socialMedia);
+            return insertedOrg;
+        });
+        return c.json(result, HttpStatusCodes.CREATED);
+    }
+    finally {
+        await closePool(pool);
+    }
+};
+/**
+ * Updates an existing organization and its related data
+ *
+ * @description Performs partial updates to an organization including related entities.
+ * Uses replace strategy for tags, websites, and social media (delete all, insert new).
+ *
+ * @param c - Hono context containing organization ID and update data
+ * @returns Updated organization data or error response
+ */
+export const patch = async (c) => {
+    const { db } = createDb(c.env);
+    const { id } = c.req.valid("param");
+    const updates = c.req.valid("json");
+    // Validate that updates are provided
+    if (Object.keys(updates).length === 0) {
+        return c.json({
+            success: false,
+            error: {
+                issues: [
+                    {
+                        code: ZOD_ERROR_CODES.INVALID_UPDATES,
+                        path: [],
+                        message: ZOD_ERROR_MESSAGES.NO_UPDATES,
+                    },
+                ],
+                name: "ZodError",
+            },
+        }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+    }
+    const { tags, websites, socialMedia, avatar, ...rest } = updates;
+    // If avatar is being updated, fetch current org to get old avatar URL
+    let processedAvatar;
+    if (avatar !== undefined) {
+        const currentOrg = await db.query.organization.findFirst({
+            where: eq(organization.id, id),
+            columns: {
+                avatar: true,
+            },
+        });
+        if (!currentOrg) {
+            return c.json({
+                message: HttpStatusPhrases.NOT_FOUND,
+            }, HttpStatusCodes.NOT_FOUND);
+        }
+        // Handle avatar removal (null means remove)
+        if (avatar === null) {
+            // Delete old R2 image if exists
+            if (currentOrg.avatar) {
+                const { deleteFromR2 } = await import("../../lib/avatar-helpers.js");
+                await deleteFromR2(currentOrg.avatar, c.env);
+            }
+            processedAvatar = null;
+        }
+        else {
+            // Process avatar upload/update
+            const avatarResult = await processAvatarUpdate(avatar, id, currentOrg.avatar ?? undefined, c.env);
+            if (!avatarResult.success) {
+                return c.json({
+                    success: false,
+                    error: {
+                        issues: [
+                            {
+                                code: "invalid_type",
+                                path: ["avatar"],
+                                message: avatarResult.error || "Invalid avatar",
+                            },
+                        ],
+                        name: "ZodError",
+                    },
+                }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+            }
+            processedAvatar = avatarResult.avatarValue;
+        }
+    }
+    const updateData = processLocationUpdates({
+        ...rest,
+        slug: slugify(rest.name?.trim() || ""),
+        ...(processedAvatar !== undefined && { avatar: processedAvatar }),
+    });
+    const [updatedOrganization] = await db.update(organization)
+        .set(updateData)
+        .where(eq(organization.id, id))
+        .returning();
+    if (!updatedOrganization) {
+        return c.json({
+            message: HttpStatusPhrases.NOT_FOUND,
+        }, HttpStatusCodes.NOT_FOUND);
+    }
+    // Handle related data updates using replace strategy
+    if (tags !== undefined) {
+        await db.delete(organizationTags)
+            .where(eq(organizationTags.organizationId, id));
+        await createOrganizationTags(db, id, tags);
+    }
+    if (websites !== undefined) {
+        await db.delete(organizationWebsites)
+            .where(eq(organizationWebsites.organizationId, id));
+        await createOrganizationWebsites(db, id, websites);
+    }
+    if (socialMedia !== undefined) {
+        await db.delete(organizationSocialMedia)
+            .where(eq(organizationSocialMedia.organizationId, id));
+        await createOrganizationSocialMedia(db, id, socialMedia);
+    }
+    return c.json(updatedOrganization, HttpStatusCodes.OK);
+};
+/**
+ * Deletes an organization and all related data
+ *
+ * @description Removes an organization from the database. Due to CASCADE constraints,
+ * all related data (websites, social media, tags) will be automatically deleted.
+ *
+ * @param c - Hono context containing organization ID
+ * @returns 204 No Content on success or 404 Not Found if organization doesn't exist
+ */
+export const remove = async (c) => {
+    const { db } = createDb(c.env);
+    const { id } = c.req.valid("param");
+    const result = await db.delete(organization).where(eq(organization.id, id));
+    if (result.rowCount === 0) {
+        return c.json({
+            message: HttpStatusPhrases.NOT_FOUND,
+        }, HttpStatusCodes.NOT_FOUND);
+    }
+    return c.body(null, HttpStatusCodes.NO_CONTENT);
+};
+/**
+ * Checks if the authenticated user owns the specified organization
+ *
+ * @description Verifies ownership without returning organization data.
+ * Used for authorization checks in the frontend.
+ *
+ * @param c - Hono context containing organization ID and authenticated user
+ * @returns Ownership status (true/false) or 404 if organization doesn't exist
+ */
+export const checkOwnership = async (c) => {
+    const { db } = createDb(c.env);
+    const { id } = c.req.valid("param");
+    const authUser = c.get("user");
+    const organizationData = await db.query.organization.findFirst({
+        where: eq(organization.id, id),
+        columns: {
+            id: true,
+            ownerId: true,
+        },
+    });
+    if (!organizationData) {
+        return c.json({
+            message: HttpStatusPhrases.NOT_FOUND,
+        }, HttpStatusCodes.NOT_FOUND);
+    }
+    const isOwner = organizationData.ownerId === authUser.id;
+    return c.json({
+        isOwner,
+    }, HttpStatusCodes.OK);
+};
+/**
+ * Checks if an organization name is available
+ *
+ * @description Verifies if the provided name is unique in the database.
+ * When taken, returns similar available slugs using pg_trgm similarity.
+ * Used for name validation in the frontend.
+ *
+ * @param c - Hono context containing organization name
+ * @returns Availability status and suggestions if taken
+ */
+// Todo: Add rate limit to this route
+export const checkOrganizationName = async (c) => {
+    const { db } = createDb(c.env);
+    const { name } = c.req.valid("query");
+    if (!name?.trim()) {
+        return c.json({ message: "Name is required" }, HttpStatusCodes.UNPROCESSABLE_ENTITY);
+    }
+    const slug = slugify(name.trim());
+    // Check if slug exists using case-insensitive comparison
+    const exists = await db
+        .select({
+        id: organization.id,
+        slug: organization.slug,
+    })
+        .from(organization)
+        .where(sql `LOWER(TRIM(${organization.slug})) = ${slug.toLowerCase()}`)
+        .limit(1);
+    if (exists.length === 0) {
+        return c.json({ exists: false }, HttpStatusCodes.OK);
+    }
+    // Quick predefined suggestions
+    const candidates = [
+        `${slug}-org`,
+        `${slug}-team`,
+        `${slug}-club`,
+        `${slug}-league`,
+        `${slug}-hq`,
+    ];
+    // Get first 3 that don't exist
+    const available = await db.execute(sql `
+    SELECT s.candidate_slug AS slug
+    FROM unnest(ARRAY[${sql.join(candidates.map(c => sql `${c}`), sql `, `)}]) AS s(candidate_slug)
+    WHERE NOT EXISTS (
+      SELECT 1 FROM organization o WHERE o.slug = s.candidate_slug
+    )
+    LIMIT 3
+  `);
+    return c.json({
+        exists: true,
+        suggestions: available.rows.map(r => r.slug),
+    }, HttpStatusCodes.OK);
+};