playcademy 0.11.14 → 0.12.0

package/dist/templates/api/sample-route-with-db.ts.template

@@ -0,0 +1,141 @@
+/**
+ * Sample API route with database
+ *
+ * This route will be available at: https://<your-game-slug>.playcademy.gg/api/hello
+ */
+
+import { desc } from 'drizzle-orm'
+
+import { getDb, schema } from '../../db'
+
+import type { Context } from 'hono'
+
+/**
+ * Request body for score submission
+ */
+interface ScoreSubmission {
+    /** Score value (must be >= 0) */
+    score: number
+    /** Optional level where score was earned (defaults to 1) */
+    level?: number
+}
+
+/**
+ * GET /api/hello
+ *
+ * Retrieve recent scores with user information
+ */
+export async function GET(c: Context): Promise<Response> {
+    try {
+        const db = getDb(c.env.DB)
+
+        const scores = await db.query.scores.findMany({
+            limit: 10,
+            orderBy: desc(schema.scores.id),
+            with: {
+                user: true,
+            },
+        })
+
+        return c.json({
+            success: true,
+            data: {
+                scores,
+                total: scores.length,
+            },
+        })
+    } catch (error) {
+        return c.json(
+            {
+                success: false,
+                error: 'Failed to fetch scores',
+                details: error instanceof Error ? error.message : String(error),
+            },
+            500,
+        )
+    }
+}
+
+/**
+ * POST /api/hello
+ *
+ * Submit a new score for the current user
+ */
+export async function POST(c: Context): Promise<Response> {
+    try {
+        const body = (await c.req.json()) as ScoreSubmission
+
+        if (!body.score || body.score < 0) {
+            return c.json(
+                {
+                    success: false,
+                    error: 'Invalid score value',
+                },
+                400,
+            )
+        }
+
+        const db = getDb(c.env.DB)
+
+        // Get or create a demo user
+        let user = await db.select().from(schema.users).limit(1).get()
+
+        if (!user) {
+            // Auto-create demo user on first score submission
+            const [newUser] = await db
+                .insert(schema.users)
+                .values({
+                    name: 'Demo Player',
+                    createdAt: new Date().toISOString(),
+                    updatedAt: new Date().toISOString(),
+                })
+                .returning()
+
+            if (!newUser) {
+                return c.json(
+                    {
+                        success: false,
+                        error: 'Failed to create user',
+                    },
+                    500,
+                )
+            }
+
+            user = newUser
+        }
+
+        const [newScore] = await db
+            .insert(schema.scores)
+            .values({
+                userId: user.id,
+                score: body.score,
+                level: body.level ?? 1,
+                createdAt: new Date().toISOString(),
+            })
+            .returning()
+
+        return c.json({
+            success: true,
+            data: {
+                score: newScore,
+            },
+        })
+    } catch (error) {
+        return c.json(
+            {
+                success: false,
+                error: 'Failed to save score',
+                details: error instanceof Error ? error.message : String(error),
+            },
+            500,
+        )
+    }
+}
+
+/**
+ * Environment variables available via c.env:
+ * - c.env.PLAYCADEMY_API_KEY - Game-scoped API key
+ * - c.env.GAME_ID - Your game's unique ID
+ * - c.env.PLAYCADEMY_BASE_URL - Playcademy platform URL
+ * - c.env.DB - D1 database binding
+ */

package/dist/templates/config/playcademy.config.js.template

@@ -0,0 +1,4 @@
+/** @type {import('playcademy/types').PlaycademyConfig} */
+export default {
+    name: '{{GAME_NAME}}',{{GAME_DESCRIPTION}}{{GAME_EMOJI}}{{INTEGRATIONS_CONFIG}}
+}

package/dist/templates/config/playcademy.config.json.template

@@ -0,0 +1,3 @@
+{
+    "name": "{{GAME_NAME}}"{{GAME_DESCRIPTION}}{{GAME_EMOJI}}{{INTEGRATIONS_CONFIG}}
+}

package/dist/templates/config/timeback-config.js.template

@@ -0,0 +1,8 @@
+        // TimeBack integration configuration
+        // See https://docs.playcademy.com/timeback for more details
+        timeback: {
+            course: {
+                subjects: {{SUBJECTS}},{{DEFAULT_SUBJECT}}
+                grades: {{GRADES}},
+            },
+        },

package/dist/templates/database/db-index.ts.template

@@ -0,0 +1,21 @@
+/**
+ * Database Client
+ *
+ * Initialize Drizzle ORM with D1 database binding.
+ */
+
+import { drizzle } from 'drizzle-orm/d1'
+
+import * as schema from './schema'
+
+import type { D1Database } from '@cloudflare/workers-types'
+
+/**
+ * Get a Drizzle client instance from a D1 database binding
+ */
+export function getDb(d1: D1Database) {
+    return drizzle(d1, { schema })
+}
+
+export { schema }
+

package/dist/templates/database/db-schema-index.ts.template

@@ -0,0 +1,8 @@
+/**
+ * Schema Index
+ *
+ * Export all schema definitions from this file.
+ */
+
+export * from './users'
+export * from './scores'

package/dist/templates/database/db-schema-scores.ts.template

@@ -0,0 +1,43 @@
+/**
+ * Scores Schema
+ *
+ * Define game score tables here using Drizzle ORM.
+ */
+
+import { relations } from 'drizzle-orm'
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+import { users } from './users'
+
+/**
+ * Scores table
+ *
+ * Tracks game scores per user with level information
+ */
+export const scores = sqliteTable('scores', {
+    /** Unique score ID */
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** Reference to user who earned this score */
+    userId: integer('user_id')
+        .notNull()
+        .references(() => users.id),
+    /** Score value (points earned) */
+    score: integer('score').notNull(),
+    /** Level where score was earned */
+    level: integer('level').notNull(),
+    /** Timestamp when score was created */
+    createdAt: text('created_at').notNull(),
+})
+
+/**
+ * Score relations
+ *
+ * Defines how scores relate to users (many-to-one)
+ */
+export const scoresRelations = relations(scores, ({ one }) => ({
+    user: one(users, {
+        fields: [scores.userId],
+        references: [users.id],
+    }),
+}))
+

package/dist/templates/database/db-schema-users.ts.template

@@ -0,0 +1,23 @@
+/**
+ * Users Schema
+ *
+ * Define user-related tables here using Drizzle ORM.
+ */
+
+import { integer, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+
+/**
+ * Users table
+ *
+ * Stores basic user information
+ */
+export const users = sqliteTable('users', {
+    /** Unique user ID */
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    /** User's display name */
+    name: text('name').notNull(),
+    /** Timestamp when user was created */
+    createdAt: text('created_at').notNull(),
+    /** Timestamp when user was last updated */
+    updatedAt: text('updated_at').notNull(),
+})

package/dist/templates/database/db-seed.ts.template

@@ -0,0 +1,52 @@
+/**
+ * Database Seed
+ *
+ * Populate the database with initial data.
+ */
+
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+
+import { getPath } from 'playcademy/db'
+
+import * as schema from './schema'
+
+/**
+ * Seed the database with initial data
+ */
+export async function seed() {
+    const dbPath = getPath()
+    const sqlite = new Database(dbPath)
+    const db = drizzle(sqlite, { schema })
+
+    // Seed users
+    const [user] = await db
+        .insert(schema.users)
+        .values({
+            name: 'Demo User',
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        })
+        .returning()
+
+    if (!user) {
+        throw new Error('Failed to seed user')
+    }
+
+    // Seed scores
+    await db.insert(schema.scores).values({
+        userId: user.id,
+        score: 100,
+        level: 1,
+        createdAt: new Date().toISOString(),
+    })
+
+    sqlite.close()
+}
+
+/**
+ * Run seed if this file is executed directly (from e.g. a package.json script)
+ */
+if (import.meta.url === `file://${process.argv[1]}`) {
+    seed().catch(console.error)
+}

package/dist/templates/database/db-types.ts.template

@@ -0,0 +1,21 @@
+/**
+ * Database Types
+ *
+ * Type-safe exports inferred from Drizzle schema
+ */
+
+import * as schema from './schema'
+
+import type { InferSelectModel } from 'drizzle-orm'
+
+/** User record from database */
+export type User = InferSelectModel<typeof schema.users>
+
+/** Score record from database */
+export type Score = InferSelectModel<typeof schema.scores>
+
+/** Score with user information populated */
+export type ScoreWithUser = Score & {
+    user: User | null
+}
+

package/dist/templates/database/drizzle-config.ts.template

@@ -0,0 +1,13 @@
+import { getPath } from 'playcademy/db'
+
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+    schema: './db/schema/index.ts',
+    out: './db/migrations',
+    dialect: 'sqlite',
+    dbCredentials: {
+        url: getPath(),
+    },
+})
+

package/dist/templates/database/package.json.template

@@ -0,0 +1,20 @@
+{
+    "name": "{{GAME_NAME}}-backend",
+    "version": "0.0.0",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "db:push": "drizzle-kit push",
+        "db:studio": "drizzle-kit studio"
+    },
+    "dependencies": {
+        "drizzle-orm": "^0.42.0",
+        "better-sqlite3": "^12.0.0"
+    },
+    "devDependencies": {
+        "drizzle-kit": "^0.30.0",
+        "@types/better-sqlite3": "^7.6.0",
+        "@cloudflare/workers-types": "^4.0.0"
+    }
+}
+

package/dist/templates/gitignore.template

@@ -0,0 +1,17 @@
+# dependencies
+node_modules/
+
+# logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# environment
+.env
+
+# os
+.DS_Store

package/dist/templates/playcademy-gitignore.template

@@ -0,0 +1,3 @@
+*.zip
+*.pid
+db

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import { OrganizationConfig, CourseConfig, ComponentConfig, ResourceConfig, ComponentResourceConfig } from '@playcademy/timeback/types';
-import * as _hono_node_server from '@hono/node-server';
+import { Miniflare } from 'miniflare';
 import * as chokidar from 'chokidar';
 
 /**
@@ -24,12 +24,31 @@ interface TimebackIntegrationConfig {
     /** Component-Resource link overrides */
     componentResource?: Partial<ComponentResourceConfig>;
 }
+/**
+ * Custom API routes integration
+ */
+interface CustomRoutesIntegration {
+    /** Directory for custom API routes (defaults to 'server/api') */
+    directory?: string;
+}
+/**
+ * Database integration
+ */
+interface DatabaseIntegration {
+    /** Database directory (defaults to 'db') */
+    directory?: string;
+}
 /**
  * Integrations configuration
+ * All backend features (database, custom routes, external services) are configured here
  */
 interface IntegrationsConfig {
     /** TimeBack integration (optional) */
     timeback?: TimebackIntegrationConfig;
+    /** Custom API routes (optional) */
+    customRoutes?: CustomRoutesIntegration | boolean;
+    /** Database (optional) */
+    database?: DatabaseIntegration | boolean;
 }
 /**
  * Unified Playcademy configuration
@@ -52,12 +71,7 @@ interface PlaycademyConfig {
     externalUrl?: string;
     /** Game platform */
     platform?: 'web' | 'unity' | 'godot';
-    /** Backend configuration */
-    backend?: {
-        /** Custom API routes directory (defaults to 'api') */
-        directory?: string;
-    };
-    /** External integrations */
+    /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
 }
 
@@ -74,6 +88,10 @@ declare function loadConfig(configPath?: string): Promise<PlaycademyConfig>;
  */
 declare function validateConfig(config: unknown): asserts config is PlaycademyConfig;
 
+/**
+ * Development server utilities
+ */
+
 interface DevServerOptions {
     port: number;
     config: PlaycademyConfig;
@@ -89,19 +107,18 @@ interface DevServerOptions {
     platformUrl?: string;
 }
 /**
- * Start the local development server
- * Returns the server instance which can be closed for hot reload
+ * Start the local development server using Miniflare
+ * Returns the Miniflare instance which can be disposed for hot reload
  */
-declare function startDevServer(options: DevServerOptions): Promise<_hono_node_server.ServerType>;
+declare function startDevServer(options: DevServerOptions): Promise<Miniflare>;
 
-/**
- * Hot reload utilities for dev server
- */
 interface HotReloadOptions {
     /** Custom success logger (defaults to CLI logger) */
-    onSuccess?: (changedPath?: string) => void;
+    onSuccess?: (changedPath?: string, eventType?: string) => void;
     /** Custom error logger (defaults to CLI logger) */
     onError?: (error: unknown) => void;
+    /** Playcademy config (to determine backend directory) */
+    config?: PlaycademyConfig | null;
 }
 /**
  * Start watching files for changes and reload server