@newschools/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 New Schools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# @newschools/nuxt
+
+Nuxt module for integrating New Schools learning content into your applications.
+
+## Features
+
+✨ **Auto-imported composables** - `useAsyncNewSchools` available everywhere  
+🔒 **Type-safe** - Full TypeScript support with entity types  
+⚡ **SSR-compatible** - Built on Nuxt's `useAsyncData`  
+🎯 **Simple API** - Fetch journeys, waypoints, and activities with ease  
+🔑 **API key authentication** - Secure access to your organisation's content
+
+## Installation
+
+```bash
+# Using npm
+npm install @newschools/nuxt
+
+# Using yarn
+yarn add @newschools/nuxt
+
+# Using pnpm
+pnpm add @newschools/nuxt
+
+# Using bun
+bun add @newschools/nuxt
+```
+
+## Setup
+
+### 1. Add module to `nuxt.config.ts`
+
+```typescript
+export default defineNuxtConfig({
+  modules: ["@newschools/nuxt"],
+});
+```
+
+### 2. Configure API key
+
+Add your New Schools API key to `.env`:
+
+```env
+NUXT_PUBLIC_NEWSCHOOLS_API_KEY=ns_live_xxxxxxxxxxxxx
+```
+
+Or configure directly in `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ["@newschools/nuxt"],
+
+  newschools: {
+    apiKey: "ns_live_xxxxxxxxxxxxx",
+    baseUrl: "https://newschools.ai", // optional, defaults to production
+  },
+});
+```
+
+## Usage
+
+The `useAsyncNewSchools` composable is auto-imported and available in all components, pages, and composables.
+
+### List Journeys
+
+```vue
+<script setup lang="ts">
+const {
+  data: journeys,
+  pending,
+  error,
+  refresh,
+} = await useAsyncNewSchools("journeys");
+</script>
+
+<template>
+  <div>
+    <div v-if="pending">Loading journeys...</div>
+    <div v-else-if="error">Error: {{ error.message }}</div>
+    <div v-else>
+      <div v-for="journey in journeys" :key="journey.id">
+        <h2>{{ journey.title }}</h2>
+        <p>{{ journey.description }}</p>
+      </div>
+    </div>
+  </div>
+</template>
+```
+
+### Get Single Journey
+
+```vue
+<script setup lang="ts">
+const route = useRoute();
+const slug = route.params.slug as string;
+
+const { data: journey } = await useAsyncNewSchools("journey", { id: slug });
+</script>
+
+<template>
+  <div>
+    <h1>{{ journey?.title }}</h1>
+    <p>{{ journey?.summary }}</p>
+    <img v-if="journey?.coverImageUrl" :src="journey.coverImageUrl" />
+  </div>
+</template>
+```
+
+### List Waypoints for Journey
+
+```vue
+<script setup lang="ts">
+const route = useRoute();
+const journeyId = route.params.journeyId as string;
+
+const { data: waypoints } = await useAsyncNewSchools("waypoints", {
+  journeyId,
+});
+</script>
+
+<template>
+  <div>
+    <div v-for="waypoint in waypoints" :key="waypoint.id">
+      <h3>{{ waypoint.title }}</h3>
+    </div>
+  </div>
+</template>
+```
+
+### Get Single Waypoint
+
+```vue
+<script setup lang="ts">
+const { data: waypoint } = await useAsyncNewSchools("waypoint", {
+  journeyId: "journey-123",
+  waypointId: "waypoint-456",
+});
+</script>
+```
+
+### List Activities
+
+```vue
+<script setup lang="ts">
+const { data: activities } = await useAsyncNewSchools("activities", {
+  journeyId: "journey-123",
+  waypointId: "waypoint-456",
+});
+</script>
+```
+
+### Get Single Activity
+
+```vue
+<script setup lang="ts">
+const { data: activity } = await useAsyncNewSchools("activity", {
+  journeyId: "journey-123",
+  waypointId: "waypoint-456",
+  activityId: "activity-789",
+});
+</script>
+```
+
+## API Reference
+
+### `useAsyncNewSchools(resource, params?)`
+
+Fetch data from New Schools v1 API with SSR support.
+
+**Parameters:**
+
+- `resource` - Resource type to fetch:
+  - `'journeys'` - List all journeys
+  - `'journey'` - Get single journey
+  - `'waypoints'` - List waypoints for journey
+  - `'waypoint'` - Get single waypoint
+  - `'activities'` - List activities for waypoint
+  - `'activity'` - Get single activity
+
+- `params` - Resource-specific parameters (optional for lists):
+  - Journey: `{ id: string }`
+  - Waypoint: `{ journeyId: string, waypointId?: string }`
+  - Activity: `{ journeyId: string, waypointId: string, activityId?: string }`
+
+**Returns:**
+
+`AsyncData` object with:
+
+- `data` - Fetched data (reactive)
+- `pending` - Loading state (reactive)
+- `error` - Error object if request failed (reactive)
+- `refresh()` - Function to refetch data
+
+## TypeScript Support
+
+Full type safety for all entities:
+
+```typescript
+import type {
+  Journey,
+  Waypoint,
+  Activity,
+  JourneyTheme,
+  WaypointType,
+  LayoutMode,
+} from "@newschools/nuxt";
+
+// Types are automatically inferred in useAsyncNewSchools
+const { data: journeys } = await useAsyncNewSchools("journeys");
+// journeys is typed as Journey[] | null
+
+const { data: journey } = await useAsyncNewSchools("journey", { id: "slug" });
+// journey is typed as Journey | null
+```
+
+## Advanced Usage
+
+### Manual Client (Without Nuxt Composables)
+
+For use in server routes, plugins, or non-component contexts:
+
+```typescript
+import { createClient } from "@newschools/nuxt";
+
+const client = createClient({
+  apiKey: "ns_live_xxxxxxxxxxxxx",
+  baseUrl: "https://newschools.ai", // optional
+});
+
+const journeys = await client.get<Journey[]>("/journeys");
+const journey = await client.get<Journey>("/journeys/my-slug");
+```
+
+### Custom Path Resolution
+
+For advanced integrations:
+
+```typescript
+import { NewSchoolsPathResolver } from "@newschools/nuxt";
+
+const path = NewSchoolsPathResolver.resolve("journey", "list");
+// Returns: '/journeys'
+
+const path2 = NewSchoolsPathResolver.resolve("waypoint", "get", {
+  journeyId: "123",
+  waypointId: "456",
+});
+// Returns: '/journeys/123/waypoints/456'
+```
+
+## Local Development (Testing with bun link)
+
+For testing the SDK locally before publishing:
+
+```bash
+# In the SDK package directory
+cd packages/nuxt
+bun link
+
+# In your test project
+cd ~/my-test-project
+bun link @newschools/nuxt
+```
+
+Add to your test project's `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ["@newschools/nuxt"],
+});
+```
+
+## Environment Variables
+
+| Variable                          | Description                           | Required |
+| --------------------------------- | ------------------------------------- | -------- |
+| `NUXT_PUBLIC_NEWSCHOOLS_API_KEY`  | Your New Schools API key              | Yes      |
+| `NUXT_PUBLIC_NEWSCHOOLS_BASE_URL` | API base URL (defaults to production) | No       |
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions:
+
+- API documentation: https://newschools.ai/docs
+- Contact: support@newschools.ai

package/nuxt/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * New Schools SDK - Main Entry Point
+ *
+ * Exports module, types, and utilities
+ */
+
+// Export Nuxt module
+export { default } from "./module";
+
+// Export types
+export type {
+  Journey,
+  JourneyTheme,
+  JourneyStatus,
+  Waypoint,
+  StandardWaypoint,
+  ProfileEnrichmentWaypoint,
+  WaypointType,
+  WaypointStatus,
+  LayoutMode,
+  Question,
+  Activity,
+  ActivityStatus,
+  GridPosition,
+  SuccessResponse,
+  ErrorResponse,
+  ApiResponse,
+} from "./types";
+
+// Export composable type for advanced usage
+export type { useAsyncNewSchools } from "./runtime/composables/useAsyncNewSchools";
+
+// Export client for manual usage (advanced)
+export { createClient, NewSchoolsClient } from "./runtime/client";
+export type { NewSchoolsClientConfig, RequestOptions } from "./runtime/client";
+
+// Export path resolver for custom integrations (advanced)
+export { NewSchoolsPathResolver } from "./runtime/utils/pathResolver";
+export type {
+  ResourceAction,
+  ResourceType,
+  ResourceParams,
+  JourneyParams,
+  WaypointParams,
+  ActivityParams,
+} from "./runtime/utils/pathResolver";

package/nuxt/src/module.ts

@@ -0,0 +1,98 @@
+/**
+ * New Schools Nuxt Module
+ *
+ * Nuxt module that provides composables and configuration for the New Schools SDK
+ * Auto-registers plugin and makes composables available globally
+ */
+
+import {
+  defineNuxtModule,
+  addPlugin,
+  createResolver,
+  addImportsDir,
+  addComponentsDir,
+} from "@nuxt/kit";
+
+export interface ModuleOptions {
+  /**
+   * New Schools API key
+   * Can also be set via NUXT_PUBLIC_NEWSCHOOLS_API_KEY env variable
+   */
+  apiKey?: string;
+
+  /**
+   * Base URL for New Schools API
+   * Defaults to https://newschools.ai
+   */
+  baseUrl?: string;
+
+  /**
+   * Organization slug for auto-fetch and theming
+   * When set, SDK will automatically fetch organization data on init
+   * and apply brand colors as CSS variables
+   *
+   * @example 'my-organization'
+   */
+  organizationSlug?: string;
+}
+
+export default defineNuxtModule<ModuleOptions>({
+  meta: {
+    name: "@newschools/nuxt",
+    configKey: "newschools",
+    compatibility: {
+      nuxt: "^3.0.0 || ^4.0.0",
+    },
+  },
+
+  defaults: {
+    baseUrl: "https://newschools.ai",
+  },
+
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+
+    // Vite optimizations (following Storyblok pattern)
+    if (nuxt.options.vite.optimizeDeps) {
+      nuxt.options.vite.optimizeDeps.exclude =
+        nuxt.options.vite.optimizeDeps.exclude || [];
+      nuxt.options.vite.optimizeDeps.exclude.push("fsevents");
+    }
+
+    // Transpile runtime for proper bundling
+    nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    nuxt.options.build.transpile.push("@newschools/nuxt");
+
+    // Add runtime config
+    nuxt.options.runtimeConfig.public.newschools = {
+      apiKey:
+        options.apiKey || process.env.NUXT_PUBLIC_NEWSCHOOLS_API_KEY || "",
+      baseUrl: options.baseUrl || "https://newschools.ai",
+      organizationSlug: options.organizationSlug || "",
+    };
+
+    // Register plugin
+    addPlugin(resolver.resolve("./runtime/plugin"));
+
+    // Auto-import all composables from directory (Storyblok pattern)
+    addImportsDir(resolver.resolve("./runtime/composables"));
+
+    // Auto-register public components globally
+    // Private components: prefix with _ or place in internal/ subdirectory
+    addComponentsDir({
+      path: resolver.resolve("./runtime/components"),
+      global: true,
+      pattern: "**/*.vue", // All .vue files
+      ignore: ["**/internal/**", "**/_*.vue"], // Exclude internal/ and _-prefixed
+    });
+
+    // Add CSS tokens to Nuxt's CSS array
+    nuxt.options.css.push(resolver.resolve("./runtime/styles/tokens.css"));
+
+    // Log configuration in development
+    if (nuxt.options.dev) {
+      console.log("[NewSchools Module] Registered");
+      console.log("[NewSchools Module] CSS tokens loaded");
+    }
+  },
+});

package/nuxt/src/runtime/client.ts

@@ -0,0 +1,150 @@
+/**
+ * New Schools API Client
+ *
+ * Core client for making authenticated requests to the New Schools v1 API
+ * Handles API key authentication, error handling, and response parsing
+ */
+
+import { ofetch } from "ofetch";
+import type { SuccessResponse, ErrorResponse } from "../types";
+
+/**
+ * Client configuration options
+ */
+export interface NewSchoolsClientConfig {
+  /** API key for authentication (e.g., ns_live_xxxxx) */
+  apiKey: string;
+
+  /** Base URL for API requests (defaults to production) */
+  baseUrl?: string;
+
+  /** Optional origin for CORS validation */
+  origin?: string;
+}
+
+/**
+ * Request options for API calls
+ */
+export interface RequestOptions {
+  /** HTTP method (defaults to GET) */
+  method?: "GET" | "POST" | "PUT" | "DELETE";
+
+  /** Request body for POST/PUT requests */
+  body?: unknown;
+
+  /** Additional headers */
+  headers?: Record<string, string>;
+}
+
+/**
+ * New Schools API Client
+ * Provides type-safe methods for fetching learning content
+ */
+export class NewSchoolsClient {
+  private apiKey: string;
+  private baseUrl: string;
+  private origin?: string;
+
+  constructor(config: NewSchoolsClientConfig) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://newschools.ai";
+    this.origin = config.origin;
+
+    if (!this.apiKey) {
+      throw new Error("[NewSchools] API key is required");
+    }
+  }
+
+  /**
+   * Make authenticated request to v1 API
+   *
+   * @param endpoint - API endpoint path (e.g., '/journeys' or '/journeys/123')
+   * @param options - Request options
+   * @returns Unwrapped data from SuccessResponse
+   * @throws Error with message from ErrorResponse
+   */
+  async request<T>(endpoint: string, options: RequestOptions = {}): Promise<T> {
+    const url = `${this.baseUrl}/api/v1${endpoint}`;
+
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    };
+
+    // Add origin if provided (for CORS validation)
+    if (this.origin) {
+      headers["Origin"] = this.origin;
+    }
+
+    try {
+      const response = await ofetch<SuccessResponse<T> | ErrorResponse>(url, {
+        method: options.method || "GET",
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+      });
+
+      // Handle error response
+      if (!response.success) {
+        const errorResponse = response as ErrorResponse;
+        throw new Error(errorResponse.error.message);
+      }
+
+      // Return unwrapped data from success response
+      return (response as SuccessResponse<T>).data;
+    } catch (error: any) {
+      // Re-throw with improved error message
+      if (error.data && !error.data.success) {
+        const errorResponse = error.data as ErrorResponse;
+        throw new Error(`[NewSchools API] ${errorResponse.error.message}`);
+      }
+
+      throw new Error(`[NewSchools API] ${error.message || "Request failed"}`);
+    }
+  }
+
+  /**
+   * GET request helper
+   */
+  async get<T>(endpoint: string): Promise<T> {
+    return this.request<T>(endpoint, { method: "GET" });
+  }
+
+  /**
+   * POST request helper
+   */
+  async post<T>(endpoint: string, body: unknown): Promise<T> {
+    return this.request<T>(endpoint, { method: "POST", body });
+  }
+
+  /**
+   * PUT request helper
+   */
+  async put<T>(endpoint: string, body: unknown): Promise<T> {
+    return this.request<T>(endpoint, { method: "PUT", body });
+  }
+
+  /**
+   * DELETE request helper
+   */
+  async delete<T>(endpoint: string): Promise<T> {
+    return this.request<T>(endpoint, { method: "DELETE" });
+  }
+}
+
+/**
+ * Create a new New Schools API client instance
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   apiKey: 'ns_live_xxxxx',
+ *   baseUrl: 'https://newschools.ai' // optional
+ * });
+ *
+ * const journeys = await client.get('/journeys');
+ * ```
+ */
+export function createClient(config: NewSchoolsClientConfig): NewSchoolsClient {
+  return new NewSchoolsClient(config);
+}