* Protected API route to create a new species
*
* @route POST /api/species
* @authentication Required
* @param {Object} body - Species data including datasetId, label, description, ebirdCode, callTypes
* @returns {Object} Response containing:
* - data: Created species object with call types
* @description Creates a new species with optional eBird integration and call types.
* Requires EDIT permission on the dataset. Creates entries in species, species_dataset,
* and optionally call_type tables in a single transaction.
*/
app.post("/api/species", authenticate, async (c) => {
try {
// Get user ID from JWT
const jwtPayload = (c as unknown as { jwtPayload: JWTPayload }).jwtPayload;
const userId = jwtPayload.sub;
// Database connection
const sql = neon(c.env.DATABASE_URL);
const db = drizzle(sql);
// Parse and validate request body
const body = await c.req.json();
const { id, datasetId, label, description, ebirdCode, callTypes } = body;
// Field validation
if (!id || typeof id !== 'string') {
return c.json({
error: "Missing or invalid required field: id"
}, 400);
}
if (!datasetId || typeof datasetId !== 'string') {
return c.json({
error: "Missing or invalid required field: datasetId"
}, 400);
}
if (!label || typeof label !== 'string' || label.trim().length === 0) {
return c.json({
error: "Missing or invalid required field: label"
}, 400);
}
// Length validation
if (id.length !== 12) {
return c.json({
error: "Field 'id' must be exactly 12 characters (nanoid)"
}, 400);
}
if (label.length > 100) {
return c.json({
error: "Field 'label' must be 100 characters or less"
}, 400);
}
if (description && description.length > 255) {
return c.json({
error: "Field 'description' must be 255 characters or less"
}, 400);
}
if (ebirdCode && ebirdCode.length > 12) {
return c.json({
error: "Field 'ebirdCode' must be 12 characters or less"
}, 400);
}
// Validate call types if provided
if (callTypes && (!Array.isArray(callTypes) || callTypes.some(ct => !ct.label || ct.label.length > 100))) {
return c.json({
error: "Field 'callTypes' must be an array of objects with 'label' field (max 100 chars)"
}, 400);
}
// Check if user has EDIT permission on the dataset
const hasPermission = await checkUserPermission(db, userId, datasetId.trim(), 'EDIT');
if (!hasPermission) {
return c.json({
error: "You don't have permission to create species in this dataset"
}, 403);
}
// Start transaction for atomic creation
const result = await db.transaction(async (tx) => {
const now = new Date();
// Create species record
const newSpecies = {
id: id.trim(),
label: label.trim(),
ebirdCode: ebirdCode?.trim() || null,
taxonomyVersion: ebirdCode ? '2024' : null,
description: description?.trim() || null,
createdBy: userId,
createdAt: now,
lastModified: now,
modifiedBy: userId,
owner: userId,
active: true,
};
const [createdSpecies] = await tx.insert(species).values(newSpecies).returning({
id: species.id,
label: species.label,
ebirdCode: species.ebirdCode,
taxonomyVersion: species.taxonomyVersion,
description: species.description,
createdAt: species.createdAt,
createdBy: species.createdBy,
lastModified: species.lastModified,
modifiedBy: species.modifiedBy,
active: species.active,
});
// Create species-dataset association
await tx.insert(speciesDataset).values({
speciesId: id.trim(),
datasetId: datasetId.trim(),
createdAt: now,
createdBy: userId,
lastModified: now,
modifiedBy: userId,
});
// Create call types if provided
const createdCallTypes = [];
if (callTypes && callTypes.length > 0) {
for (const callTypeData of callTypes) {
const callTypeId = nanoid(12);
const [createdCallType] = await tx.insert(callType).values({
id: callTypeId,
speciesId: id.trim(),
label: callTypeData.label.trim(),
createdBy: userId,
createdAt: now,
lastModified: now,
modifiedBy: userId,
active: true,
}).returning({
id: callType.id,
label: callType.label,
});
createdCallTypes.push(createdCallType);
}
}
return {
...createdSpecies,
callTypes: createdCallTypes
};
});
console.log("Created species:", result.id, "for dataset:", datasetId, "by user:", userId);
return c.json({
data: result
}, 201);
} catch (error) {
console.error("Error creating species:", error);
// Handle unique constraint violations
if (error instanceof Error && error.message.includes('duplicate key')) {
return c.json({
error: "A species with this ID already exists"
}, 400);
}
return c.json(
{
error: "Failed to create species",
details: error instanceof Error ? error.message : String(error),
},
500
);
}
});
/**
* Protected API route to update an existing species
*
* @route PUT /api/species/:id
* @authentication Required
* @param {string} id - Species ID in URL path
* @param {Object} body - Species data to update (label, description, ebirdCode, active)
* @returns {Object} Response containing:
* - data: Updated species object with call types
* @description Updates an existing species. Requires EDIT permission on the dataset.
* When soft deleting (active=false), also soft deletes all related call types.
*/
app.put("/api/species/:id", authenticate, async (c) => {
try {
// Get user from JWT
const jwtPayload = (c as unknown as { jwtPayload: JWTPayload }).jwtPayload;
const userId = jwtPayload.sub;
// Get species ID from URL parameters
const speciesId = c.req.param("id");
// Parse request body
const body = await c.req.json();
const { label, description, ebirdCode, active } = body;
// Connect to database
const sql = neon(c.env.DATABASE_URL);
const db = drizzle(sql);
// Check if species exists and get its associated datasets
const existingSpecies = await db
.select({
id: species.id,
active: species.active
})
.from(species)
.where(eq(species.id, speciesId))
.limit(1);
if (existingSpecies.length === 0) {
return c.json({
error: "Species not found"
}, 404);
}
// Get datasets associated with this species to check permissions
const associatedDatasets = await db
.select({ datasetId: speciesDataset.datasetId })
.from(speciesDataset)
.where(eq(speciesDataset.speciesId, speciesId));
if (associatedDatasets.length === 0) {
return c.json({
error: "Species not associated with any dataset"
}, 400);
}
// Check if user has EDIT permission on at least one associated dataset
let hasPermission = false;
for (const assoc of associatedDatasets) {
if (await checkUserPermission(db, userId, assoc.datasetId, 'EDIT')) {
hasPermission = true;
break;
}
}
if (!hasPermission) {
return c.json({
error: "You don't have permission to edit this species"
}, 403);
}
// Start transaction for atomic update
const result = await db.transaction(async (tx) => {
// Build update object with only provided fields
const updateData: Record<string, unknown> = {
lastModified: new Date(),
modifiedBy: userId,
};
// Validate and add label if provided
if (label !== undefined) {
if (typeof label !== 'string' || label.trim().length === 0) {
return c.json({
error: "Field 'label' must be a non-empty string"
}, 400);
}
if (label.length > 100) {
return c.json({
error: "Field 'label' must be 100 characters or less"
}, 400);
}
updateData.label = label.trim();
}
// Validate and add description if provided
if (description !== undefined) {
if (description !== null && typeof description !== 'string') {
return c.json({
error: "Field 'description' must be a string or null"
}, 400);
}
if (description && description.length > 255) {
return c.json({
error: "Field 'description' must be 255 characters or less"
}, 400);
}
updateData.description = description?.trim() || null;
}
// Validate and add eBird code if provided
if (ebirdCode !== undefined) {
if (ebirdCode !== null && typeof ebirdCode !== 'string') {
return c.json({
error: "Field 'ebirdCode' must be a string or null"
}, 400);
}
if (ebirdCode && ebirdCode.length > 12) {
return c.json({
error: "Field 'ebirdCode' must be 12 characters or less"
}, 400);
}
updateData.ebirdCode = ebirdCode?.trim() || null;
updateData.taxonomyVersion = ebirdCode ? '2024' : null;
}
// Add active status if provided (for soft delete)
if (active !== undefined) {
if (typeof active !== 'boolean') {
return c.json({
error: "Field 'active' must be a boolean"
}, 400);
}
updateData.active = active;
// If soft deleting species, also soft delete related records
if (!active) {
// Soft delete all call types for this species
await tx
.update(callType)
.set({
active: false,
lastModified: new Date(),
modifiedBy: userId
})
.where(eq(callType.speciesId, speciesId));
// Delete all species-dataset associations for this species (hard delete since no active field)
await tx
.delete(speciesDataset)
.where(eq(speciesDataset.speciesId, speciesId));
}
}
// Update the species
const [updatedSpecies] = await tx
.update(species)
.set(updateData)
.where(eq(species.id, speciesId))
.returning({
id: species.id,
label: species.label,
ebirdCode: species.ebirdCode,
taxonomyVersion: species.taxonomyVersion,
description: species.description,
createdAt: species.createdAt,
createdBy: species.createdBy,
lastModified: species.lastModified,
modifiedBy: species.modifiedBy,
active: species.active,
});
// Get updated call types
const callTypes = await tx
.select({
id: callType.id,
label: callType.label,
})
.from(callType)
.where(and(eq(callType.speciesId, speciesId), eq(callType.active, true)));
return {
...updatedSpecies,
callTypes
};
});
console.log("Updated species:", speciesId, "by user:", userId);
return c.json({
data: result
});
} catch (error) {
console.error("Error updating species:", error);
return c.json(
{
error: "Failed to update species",
details: error instanceof Error ? error.message : String(error),
},
500
);
}
});
/**
* Protected API route to create a new call type
*
* @route POST /api/call-types
* @authentication Required
* @param {Object} body - Call type data including id, speciesId, label
* @returns {Object} Response containing:
* - data: Created call type object
* @description Creates a new call type for a species. Requires EDIT permission on any dataset containing the species.
*/
app.post("/api/call-types", authenticate, async (c) => {
try {
// Get user ID from JWT
const jwtPayload = (c as unknown as { jwtPayload: JWTPayload }).jwtPayload;
const userId = jwtPayload.sub;
// Database connection
const sql = neon(c.env.DATABASE_URL);
const db = drizzle(sql);
// Parse and validate request body
const body = await c.req.json();
const { id, speciesId, label } = body;
// Field validation
if (!id || typeof id !== 'string' || id.length !== 12) {
return c.json({
error: "Field 'id' must be exactly 12 characters (nanoid)"
}, 400);
}
if (!speciesId || typeof speciesId !== 'string') {
return c.json({
error: "Missing or invalid required field: speciesId"
}, 400);
}
if (!label || typeof label !== 'string' || label.trim().length === 0) {
return c.json({
error: "Missing or invalid required field: label"
}, 400);
}
if (label.length > 100) {
return c.json({
error: "Field 'label' must be 100 characters or less"
}, 400);
}
// Check if species exists and get its associated datasets
const associatedDatasets = await db
.select({ datasetId: speciesDataset.datasetId })
.from(speciesDataset)
.where(eq(speciesDataset.speciesId, speciesId));
if (associatedDatasets.length === 0) {
return c.json({
error: "Species not found or not associated with any dataset"
}, 404);
}
// Check if user has EDIT permission on at least one associated dataset
let hasPermission = false;
for (const assoc of associatedDatasets) {
if (await checkUserPermission(db, userId, assoc.datasetId, 'EDIT')) {
hasPermission = true;
break;
}
}
if (!hasPermission) {
return c.json({
error: "You don't have permission to create call types for this species"
}, 403);
}
// Create call type
const now = new Date();
const [createdCallType] = await db.insert(callType).values({
id: id.trim(),
speciesId: speciesId.trim(),
label: label.trim(),
createdBy: userId,
createdAt: now,
lastModified: now,
modifiedBy: userId,
active: true,
}).returning({
id: callType.id,
speciesId: callType.speciesId,
label: callType.label,
createdAt: callType.createdAt,
active: callType.active,
});
console.log("Created call type:", createdCallType.id, "for species:", speciesId, "by user:", userId);
return c.json({
data: createdCallType
}, 201);
} catch (error) {
console.error("Error creating call type:", error);
if (error instanceof Error && error.message.includes('duplicate key')) {
return c.json({
error: "A call type with this ID already exists"
}, 400);
}
return c.json(
{
error: "Failed to create call type",
details: error instanceof Error ? error.message : String(error),
},
500
);
}
});
/**
* Protected API route to update an existing call type
*
* @route PUT /api/call-types/:id
* @authentication Required
* @param {string} id - Call type ID in URL path
* @param {Object} body - Call type data to update (label, active)
* @returns {Object} Response containing:
* - data: Updated call type object
* @description Updates an existing call type. Requires EDIT permission on any dataset containing the parent species.
*/
app.put("/api/call-types/:id", authenticate, async (c) => {
try {
// Get user from JWT
const jwtPayload = (c as unknown as { jwtPayload: JWTPayload }).jwtPayload;
const userId = jwtPayload.sub;
// Get call type ID from URL parameters
const callTypeId = c.req.param("id");
// Parse request body
const body = await c.req.json();
const { label, active } = body;
// Connect to database
const sql = neon(c.env.DATABASE_URL);
const db = drizzle(sql);
// Check if call type exists and get its species
const existingCallType = await db
.select({
id: callType.id,
speciesId: callType.speciesId,
active: callType.active
})
.from(callType)
.where(eq(callType.id, callTypeId))
.limit(1);
if (existingCallType.length === 0) {
return c.json({
error: "Call type not found"
}, 404);
}
const speciesId = existingCallType[0].speciesId;
// Get datasets associated with the species to check permissions
const associatedDatasets = await db
.select({ datasetId: speciesDataset.datasetId })
.from(speciesDataset)
.where(eq(speciesDataset.speciesId, speciesId));
// Check if user has EDIT permission on at least one associated dataset
let hasPermission = false;
for (const assoc of associatedDatasets) {
if (await checkUserPermission(db, userId, assoc.datasetId, 'EDIT')) {
hasPermission = true;
break;
}
}
if (!hasPermission) {
return c.json({
error: "You don't have permission to edit this call type"
}, 403);
}
// Build update object with only provided fields
const updateData: Record<string, unknown> = {
lastModified: new Date(),
modifiedBy: userId,
};
// Validate and add label if provided
if (label !== undefined) {
if (typeof label !== 'string' || label.trim().length === 0) {
return c.json({
error: "Field 'label' must be a non-empty string"
}, 400);
}
if (label.length > 100) {
return c.json({
error: "Field 'label' must be 100 characters or less"
}, 400);
}
updateData.label = label.trim();
}
// Add active status if provided (for soft delete)
if (active !== undefined) {
if (typeof active !== 'boolean') {
return c.json({
error: "Field 'active' must be a boolean"
}, 400);
}
updateData.active = active;
}
// Update the call type
const [updatedCallType] = await db
.update(callType)
.set(updateData)
.where(eq(callType.id, callTypeId))
.returning({
id: callType.id,
speciesId: callType.speciesId,
label: callType.label,
createdAt: callType.createdAt,
lastModified: callType.lastModified,
active: callType.active,
});
console.log("Updated call type:", callTypeId, "by user:", userId);
return c.json({
data: updatedCallType
});
} catch (error) {
console.error("Error updating call type:", error);
return c.json(
{
error: "Failed to update call type",
details: error instanceof Error ? error.message : String(error),
},
500
);
}
});
/**