odyssey: Skill for Claude Code

Strapi v4.22 Patterns for Odyssey

CRITICAL: v4 Only

This codebase uses Strapi v4.22. NEVER use v5 patterns:

• Entity Service API (v4) — NOT Document Service API (v5)
• Numeric id — NOT documentId
• Nested { data: { attributes: {} } } responses — NOT flat responses

Reading a Schema

Before writing any request function, read the content type's schema:

backend/src/api/{type}/content-types/{type}/schema.json

The schema tells you every field name, type, relation, enum value, and constraint. Do not guess field names from component code — read the schema.

Query Building with qs

All queries go through fetchAPI() which uses qs.stringify(). Common patterns:

Filtering

// Exact match
filters: { status: { $eq: "published" } }

// Multiple values
filters: { type: { $in: ["knowledge", "skill"] } }

// Nested relation filter
filters: { tags: { name: { $containsi: "python" } } }

// Combined
filters: {
  status: { $eq: "published" },
  focusArea: { $eq: "technical" },
  isHidden: { $eq: false }
}

Populating Relations

// Simple: just get IDs
populate: { tags: true }

// With field selection (reduces payload)
populate: { lessons: { fields: ["name", "slug", "orderIndex"] } }

// Deep populate
populate: {
  lessons: {
    populate: { notes: true, highlights: true }
  }
}

// NEVER use populate: "*" — it pulls the entire relation graph

Pagination

pagination: { page: 1, pageSize: 25 }   // page-based
pagination: { start: 0, limit: 25 }     // offset-based

Sorting

sort: ["name:asc"];
sort: ["createdAt:desc", "name:asc"];

Request Function Pattern

Every function in lib/requests/ follows:

export async function getDropletsByFilter(
  focusArea: string,
): Promise<Droplet[]> {
  return fetchAPI<Droplet[]>("/droplets", {
    urlParams: {
      filters: { focusArea: { $eq: focusArea }, status: { $eq: "published" } },
      populate: { tags: true, lessons: { fields: ["name", "slug"] } },
      sort: ["name:asc"],
    },
    next: { tags: [CACHE_TAGS.droplets], revalidate: 900 },
  });
}