@newschools/sdk 0.1.0

package/nuxt/src/runtime/utils/pathResolver.ts

@@ -0,0 +1,164 @@
+/**
+ * New Schools Path Resolver
+ *
+ * Responsible for resolving API endpoint paths for different resource types
+ * Follows DDD single responsibility principle - only handles path resolution
+ *
+ * Adding new resources:
+ * 1. Add resource type to ResourceType union
+ * 2. Add resolver function to RESOLVERS registry
+ * 3. Type safety ensures correct parameters
+ */
+
+/**
+ * Resource type discriminator
+ * Determines whether we're fetching a list or single entity
+ */
+export type ResourceAction = "list" | "get";
+
+/**
+ * Parameters for different resource types
+ */
+export interface JourneyParams {
+  id?: string;
+}
+
+export interface WaypointParams {
+  journeyId: string;
+  waypointId?: string;
+}
+
+export interface ActivityParams {
+  journeyId: string;
+  waypointId: string;
+  activityId?: string;
+}
+
+/**
+ * Union of all possible parameter types
+ */
+export type ResourceParams = JourneyParams | WaypointParams | ActivityParams;
+
+/**
+ * Path resolver function signature
+ * Takes action and params, returns endpoint path
+ */
+type PathResolverFn<T extends ResourceParams> = (
+  action: ResourceAction,
+  params?: T,
+) => string;
+
+/**
+ * Registry of path resolvers for each resource type
+ * Each resolver is responsible for building paths for that resource
+ */
+const RESOLVERS = {
+  /**
+   * Journey path resolver
+   * - List: /journeys
+   * - Get: /journeys/{id}
+   */
+  journey: ((action: ResourceAction, params?: JourneyParams): string => {
+    if (action === "list") {
+      return "/journeys";
+    }
+
+    if (!params?.id) {
+      throw new Error("[PathResolver] Journey ID is required for get action");
+    }
+
+    return `/journeys/${params.id}`;
+  }) as PathResolverFn<JourneyParams>,
+
+  /**
+   * Waypoint path resolver
+   * - List: /journeys/{journeyId}/waypoints
+   * - Get: /journeys/{journeyId}/waypoints/{waypointId}
+   */
+  waypoint: ((action: ResourceAction, params?: WaypointParams): string => {
+    if (!params?.journeyId) {
+      throw new Error("[PathResolver] journeyId is required for waypoints");
+    }
+
+    if (action === "list") {
+      return `/journeys/${params.journeyId}/waypoints`;
+    }
+
+    if (!params.waypointId) {
+      throw new Error("[PathResolver] waypointId is required for get action");
+    }
+
+    return `/journeys/${params.journeyId}/waypoints/${params.waypointId}`;
+  }) as PathResolverFn<WaypointParams>,
+
+  /**
+   * Activity path resolver
+   * - List: /journeys/{journeyId}/waypoints/{waypointId}/activities
+   * - Get: /journeys/{journeyId}/waypoints/{waypointId}/activities/{activityId}
+   */
+  activity: ((action: ResourceAction, params?: ActivityParams): string => {
+    if (!params?.journeyId || !params?.waypointId) {
+      throw new Error(
+        "[PathResolver] journeyId and waypointId are required for activities",
+      );
+    }
+
+    if (action === "list") {
+      return `/journeys/${params.journeyId}/waypoints/${params.waypointId}/activities`;
+    }
+
+    if (!params.activityId) {
+      throw new Error("[PathResolver] activityId is required for get action");
+    }
+
+    return `/journeys/${params.journeyId}/waypoints/${params.waypointId}/activities/${params.activityId}`;
+  }) as PathResolverFn<ActivityParams>,
+};
+
+/**
+ * Resource types that have resolvers
+ */
+export type ResourceType = keyof typeof RESOLVERS;
+
+/**
+ * New Schools Path Resolver Service
+ * Resolves API endpoint paths based on resource type and parameters
+ */
+export class NewSchoolsPathResolver {
+  /**
+   * Resolve endpoint path for a resource
+   *
+   * @param resourceType - Type of resource (journey, waypoint, activity)
+   * @param action - Action to perform (list or get)
+   * @param params - Resource-specific parameters
+   * @returns API endpoint path (e.g., "/journeys/123/waypoints")
+   *
+   * @example
+   * ```typescript
+   * // List all journeys
+   * NewSchoolsPathResolver.resolve('journey', 'list')
+   * // => '/journeys'
+   *
+   * // Get single journey
+   * NewSchoolsPathResolver.resolve('journey', 'get', { id: '123' })
+   * // => '/journeys/123'
+   *
+   * // List waypoints for journey
+   * NewSchoolsPathResolver.resolve('waypoint', 'list', { journeyId: '123' })
+   * // => '/journeys/123/waypoints'
+   * ```
+   */
+  static resolve(
+    resourceType: ResourceType,
+    action: ResourceAction,
+    params?: ResourceParams,
+  ): string {
+    const resolver = RESOLVERS[resourceType];
+
+    if (!resolver) {
+      throw new Error(`[PathResolver] Unknown resource type: ${resourceType}`);
+    }
+
+    return resolver(action, params as any);
+  }
+}

package/nuxt/src/types/api.ts

@@ -0,0 +1,44 @@
+/**
+ * API Response Types
+ * Standard API response shapes for New Schools v1 API
+ */
+
+/**
+ * Standard success response shape
+ * All successful API responses follow this structure
+ */
+export interface SuccessResponse<T = unknown> {
+  success: true;
+  data: T;
+  message: string;
+  meta?: {
+    requestId?: string;
+    timestamp?: string;
+    took?: number; // Response time in ms
+  };
+}
+
+/**
+ * Standard error response shape
+ * All error API responses follow this structure
+ */
+export interface ErrorResponse {
+  success: false;
+  error: {
+    code: string; // Machine-readable error code (e.g., "JOURNEY_NOT_FOUND")
+    message: string; // Human-readable error message
+    statusCode: number; // HTTP status code
+    details?: unknown; // Optional context (validation errors, field-level details, etc.)
+    stack?: string; // Stack trace (only included in development mode)
+  };
+  meta?: {
+    requestId?: string;
+    timestamp?: string;
+    path?: string;
+  };
+}
+
+/**
+ * Union type for all API responses
+ */
+export type ApiResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;

package/nuxt/src/types/entities.ts

@@ -0,0 +1,197 @@
+/**
+ * Entity Types for New Schools v1 API
+ * Public-facing types that match API responses
+ *
+ * Note: These are simplified versions containing only public fields.
+ * Internal implementation details (moderation, Firebase paths, etc.) are omitted.
+ */
+
+/**
+ * Journey Theme Type
+ * Available theme options that determine UI terminology
+ * - adventure: K-12, gamified learners (Journey → Waypoint → Quest)
+ * - academic: Traditional education (Course → Module → Lesson)
+ * - professional: Corporate training (Program → Milestone → Activity)
+ */
+export type JourneyTheme = "adventure" | "academic" | "professional";
+
+/**
+ * Journey Status Type
+ * - draft: Being created, not visible to students
+ * - published: Active and visible to students
+ */
+export type JourneyStatus = "draft" | "published";
+
+/**
+ * Journey Entity
+ * Top-level learning container (Course/Program)
+ * Contains waypoints with activities
+ */
+export interface Journey {
+  /** Unique identifier */
+  id: string;
+
+  /** URL-friendly identifier */
+  slug: string;
+
+  /** Journey title */
+  title: string;
+
+  /** Journey description */
+  description?: string;
+
+  /** AI-generated summary */
+  summary?: string;
+
+  /** Organisation ID this journey belongs to */
+  organisationId: string;
+
+  /**
+   * Journey visibility
+   * - private: Only visible to enrolled learners
+   * - public: Listed in marketplace, anyone can enroll
+   */
+  visibility: "private" | "public";
+
+  /** Theme determines UI terminology */
+  theme: JourneyTheme;
+
+  /** Journey status */
+  status: JourneyStatus;
+
+  /** Number of waypoints in this journey */
+  waypointCount: number;
+
+  /** Total number of activities across all waypoints */
+  activityCount: number;
+
+  /** Cover image public URL */
+  coverImageUrl?: string;
+
+  /** Creation timestamp (ISO 8601 string) */
+  createdAt: string;
+
+  /** Last update timestamp (ISO 8601 string) */
+  updatedAt: string;
+}
+
+/**
+ * Waypoint Type
+ * Four distinct types of waypoints in a journey
+ */
+export type WaypointType =
+  | "standard"
+  | "startingPoint"
+  | "checkpoint"
+  | "exitReflection";
+
+/**
+ * Layout Mode Type
+ * Determines how activities are organized within standard waypoints
+ */
+export type LayoutMode = "linear" | "grid";
+
+/**
+ * Waypoint Status Type
+ */
+export type WaypointStatus = "draft" | "published";
+
+/**
+ * Question for Profile Enrichment Waypoints
+ * AI asks these conversationally in chat interface
+ */
+export interface Question {
+  /** Unique question ID */
+  id: string;
+
+  /** Question text that AI will ask conversationally */
+  prompt: string;
+
+  /** Storage key in student journey profile */
+  profileKey: string;
+
+  /** Optional context for AI on how to approach this question */
+  guidance?: string;
+}
+
+/**
+ * Standard Waypoint
+ * Learning container with activities
+ */
+export interface StandardWaypoint {
+  id: string;
+  journeyId: string;
+  slug: string;
+  title: string;
+  description?: string;
+  order: number;
+  waypointType: "standard";
+  status: WaypointStatus;
+  layoutMode: LayoutMode;
+  activityCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Profile Enrichment Waypoint
+ * Gathers information from learners at journey start, checkpoints, or end
+ */
+export interface ProfileEnrichmentWaypoint {
+  id: string;
+  journeyId: string;
+  slug: string;
+  title: string;
+  description?: string;
+  order: number;
+  waypointType: "startingPoint" | "checkpoint" | "exitReflection";
+  status: WaypointStatus;
+  questions: Question[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Union type for all waypoint types
+ */
+export type Waypoint = StandardWaypoint | ProfileEnrichmentWaypoint;
+
+/**
+ * Activity Status Type
+ */
+export type ActivityStatus = "draft" | "published";
+
+/**
+ * Grid Position for hub & rings layout
+ * Position in 5x5 grid (0-indexed)
+ */
+export interface GridPosition {
+  row: number;
+  col: number;
+}
+
+/**
+ * Activity Entity
+ * A specific learning session within a standard waypoint
+ */
+export interface Activity {
+  id: string;
+  waypointId: string;
+  journeyId: string;
+  slug: string;
+  title: string;
+  description?: string;
+
+  /** Position in sequential order (linear mode only) */
+  order?: number;
+
+  /** Whether this activity must be completed before next (linear mode only) */
+  isLinked?: boolean;
+
+  /** Position in 5x5 hub & rings grid (grid mode only) */
+  gridPosition?: GridPosition;
+
+  status: ActivityStatus;
+  createdAt: string;
+  updatedAt: string;
+}

package/nuxt/src/types/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Type Exports for New Schools SDK
+ * Re-exports all public types
+ */
+
+// API Response Types
+export type { SuccessResponse, ErrorResponse, ApiResponse } from "./api";
+
+// Entity Types
+export type {
+  Journey,
+  JourneyTheme,
+  JourneyStatus,
+  Waypoint,
+  StandardWaypoint,
+  ProfileEnrichmentWaypoint,
+  WaypointType,
+  WaypointStatus,
+  LayoutMode,
+  Question,
+  Activity,
+  ActivityStatus,
+  GridPosition,
+} from "./entities";

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@newschools/sdk",
+  "version": "0.1.0",
+  "description": "New Schools SDK - Multi-framework components and modules for integrating New Schools learning content",
+  "type": "module",
+  "main": "./nuxt/src/module.ts",
+  "types": "./nuxt/src/module.ts",
+  "exports": {
+    ".": {
+      "import": "./nuxt/src/module.ts",
+      "types": "./nuxt/src/module.ts"
+    }
+  },
+  "files": [
+    "nuxt/src",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "newschools",
+    "sdk",
+    "nuxt",
+    "nuxt-module",
+    "react",
+    "svelte",
+    "learning",
+    "lms",
+    "api"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^3.13.0",
+    "h3": "^1.12.0",
+    "motion-v": "^1.7.4",
+    "ofetch": "^1.4.0"
+  },
+  "devDependencies": {
+    "@nuxt/schema": "^3.13.0",
+    "typescript": "^5.6.3"
+  },
+  "peerDependencies": {
+    "nuxt": "^3.0.0 || ^4.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}